@theholocron/discord-client 1.57.1-alpha.2 → 1.58.0-alpha.10

package/README.md

@@ -1,3 +1,5 @@
+<!-- alex disable host-hostess -->
+
 # @theholocron/discord-client
 
 A TypeScript client for Discord — posts messages through webhooks, and (with a bot token) provisions a server's channels, roles and webhooks.
@@ -99,19 +101,20 @@ 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; `get(id)` — a user's name; `guilds({ limit, after })` — `GET /users/@me/guilds`, the servers the bot is in and whether it owns each (look here before retrying `guilds.create`)                                        |
-| `client.application` | `get`, `modify` (the bot's own application: description, tags, install settings, URLs, and `flags` for the privileged-intent toggles; `redirect_uris` can be read but not written, so add them in the developer portal)                                                |
-| `client.guilds`      | `get`, `modify`, `channels`, `createChannel`, `roles`, `createRole`, `modifyRole`, `create`, `delete`, `emojis`, `member`, `members`, `membersWithRole`, `addMemberRole`, `removeMemberRole`, `welcomeScreen`, `modifyWelcomeScreen`, `onboarding`, `modifyOnboarding` |
-| `client.channels`    | `modify`, `webhooks`, `createWebhook`, `createMessage`, `createInvite`, `messages`, `pin`, `deleteMessage`                                                                                                                                                             |
-| `client.webhooks`    | `modify` (name, avatar), `delete`                                                                                                                                                                                                                                      |
+| Resource             | Methods                                                                                                                                                                                                                                                                                              |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client.users`       | `me()` — `GET /users/@me`, a cheap token check; `get(id)` — a user's name; `guilds({ limit, after })` — `GET /users/@me/guilds`, the servers the bot is in and whether it owns each (look here before retrying `guilds.create`)                                                                      |
+| `client.application` | `get`, `modify` (the bot's own application: description, tags, install settings, URLs, and `flags` for the privileged-intent toggles; `redirect_uris` can be read but not written, so add them in the developer portal)                                                                              |
+| `client.guilds`      | `get`, `modify`, `channels`, `createChannel`, `roles`, `createRole`, `modifyRole`, `create`, `delete`, `emojis`, `member`, `members`, `membersWithRole`, `addMemberRole`, `removeMemberRole`, `welcomeScreen`, `modifyWelcomeScreen`, `onboarding`, `modifyOnboarding`                               |
+| `client.channels`    | `modify`, `webhooks`, `createWebhook`, `createMessage`, `message`, `editMessage`, `createInvite`, `messages`, `pin`, `deleteMessage`                                                                                                                                                                 |
+| `client.threads`     | `createForumPost` — a post in a forum channel with its tags and first message; `modify` — a thread's title, tags, archived and locked state; `active` — the server's active threads; `archived` — one page of a channel's archived threads; `inChannel` — every post of a forum, active and archived |
+| `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
+`channels.createMessage`, `channels.editMessage` and the first message of `threads.createForumPost` turn 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`.
@@ -135,6 +138,10 @@ hands it over, `channels.createInvite` makes the link to join it, and `guilds.de
 `executeAndWait` posts and returns the message id and `deleteMessage` removes it, so a check can post a line, read it back
 with `channels.messages`, and clean up. `channels.pin` pins a message.
 
+### Forum posts
+
+`guilds.createChannel` with `type: ChannelType.Forum` and `available_tags` makes a forum; `channels.modify` replaces its tags (send the whole list, with each kept tag's `id`). `threads.createForumPost(channelId, { name, applied_tags, message })` makes a post, and `message.flags: MessageFlag.SuppressNotifications` posts it without notifying anyone, as a backfill should. `threads.modify` retitles or retags a post, and writing to an archived post unarchives it. Discord hides a post that has been quiet for a while, so `threads.inChannel(guildId, forumId)` reads the archived pages too before you decide a post does not exist. Creating a post is not idempotent: look it up first. Only the bot, which owns its posts, and members with Manage Threads can change a post's tags.
+
 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

@@ -1,6 +1,10 @@
+/** What fetching a webhook by id and token returns. */
 interface DiscordWebhookInfo {
+  /** The webhook id. */
   id: string;
+  /** The webhook name. */
   name: string;
+  /** Id of the server the webhook belongs to, when Discord includes it. */
   guild_id?: string;
 }
 /** Parse a Discord webhook URL into its id and token parts. */
@@ -8,41 +12,64 @@ export declare function parseWebhookUrl(url: string): {
   id: string;
   token: string;
 };
+/** Options for `createDiscordClient`. */
 interface DiscordClientOptions {
   /** Override base URL for testing. Defaults to https://discord.com/api/v10. */
   baseUrl?: string;
   /** Override fetch for testing. Defaults to globalThis.fetch. */
   fetch?: typeof fetch;
 }
+/** Options for `createDiscordBotClient`. */
 export interface DiscordBotClientOptions {
   /** Bot token from the Discord developer portal (Bot → Reset Token). */
   botToken: string;
-  /** Override base URL for testing. Defaults to https://discord.com/api/v10. */
+  /**
+   * Override base URL for testing. Defaults to https://discord.com/api/v10.
+   * The bot token is sent to whatever host this names, so never derive it from untrusted input.
+   */
   baseUrl?: string;
   /** Override fetch for testing. Defaults to globalThis.fetch. */
   fetch?: typeof fetch;
   /** Per-request deadline in milliseconds. Defaults to 15000. */
   timeoutMs?: number;
-  /** Retries after a 429 (rate limit) before giving up. Defaults to 3. */
+  /**
+   * Retries after a 429 (rate limit) before giving up. Defaults to 3.
+   * Each retry waits for the `Retry-After` Discord sends; a wait longer than 10 seconds fails immediately.
+   */
   maxRetries?: number;
   /** Wait between rate-limit retries; a test seam. Defaults to `setTimeout`. */
   sleep?: (ms: number) => Promise<void>;
 }
 /** Discord channel `type` values this client creates or reads. */
 export declare const ChannelType: {
+  /** A text channel. */
   readonly Text: 0;
+  /** A category that groups channels. */
   readonly Category: 4;
+  /** An announcement channel. */
   readonly Announcement: 5;
+  /** A forum channel. */
   readonly Forum: 15;
 };
+/** Bits of a message's `flags` that a bot may set when it posts. */
+export declare const MessageFlag: {
+  /** Posts without notifying anyone, as a backfill of many messages should. */
+  readonly SuppressNotifications: number;
+};
+/** A Discord account, as the API returns it. */
 export interface DiscordUser {
+  /** The user id. */
   id: string;
+  /** The account's username. */
   username: string;
+  /** Whether the account is a bot. */
   bot?: boolean;
 }
 /** A server as `GET /users/@me/guilds` lists it: a summary, not the full guild. */
 export interface DiscordUserGuild {
+  /** The server id. */
   id: string;
+  /** The server name. */
   name: string;
   /** Whether the caller (here, the bot) owns the server. */
   owner: boolean;
@@ -51,13 +78,16 @@ export interface DiscordUserGuild {
 }
 /** Page options for `users.guilds`; Discord allows a `limit` of 1–200; values outside that are clamped. */
 export interface ListUserGuildsInput {
+  /** How many servers to return, 1 to 200. */
   limit?: number;
   /** Return servers after this server id. */
   after?: string;
 }
 /** Guild fields `guilds.modify` can change; the numeric enums are Discord's own. */
 export interface DiscordGuild {
+  /** The server id. */
   id: string;
+  /** The server name. */
   name: string;
   /** 0 none, 1 low, 2 medium, 3 high, 4 very high. */
   verification_level?: number;
@@ -65,84 +95,136 @@ export interface DiscordGuild {
   default_message_notifications?: number;
   /** 0 disabled, 1 members without roles, 2 all members. */
   explicit_content_filter?: number;
+  /** Id of the channel for system messages, or `null` for none. */
   system_channel_id?: string | null;
   /** Bitfield of system-channel messages to suppress. */
   system_channel_flags?: number;
+  /** Id of the rules channel, or `null` for none. */
   rules_channel_id?: string | null;
+  /** Id of the channel for Discord's community updates, or `null` for none. */
   public_updates_channel_id?: string | null;
+  /** The server's preferred locale, such as `en-US`. */
   preferred_locale?: string;
+  /** The server description, or `null` when unset. */
   description?: string | null;
   /** `COMMUNITY` here means the community features (welcome screen, onboarding) are available. */
   features?: string[];
 }
+/** What `PATCH /guilds/{id}` takes; a field left out is left alone. */
 export interface ModifyGuildInput {
+  /** A new server name. */
   name?: string;
   /** Hands the server to another user; only the current owner (never a bot that does not own it) may. */
   owner_id?: string;
+  /** Verification level: 0 none, 1 low, 2 medium, 3 high, 4 very high. */
   verification_level?: number;
+  /** Notification default: 0 all messages, 1 only @mentions. */
   default_message_notifications?: number;
+  /** Content filter: 0 disabled, 1 members without roles, 2 all members. */
   explicit_content_filter?: number;
+  /** Id of the channel for system messages, or `null` for none. */
   system_channel_id?: string | null;
+  /** Bitfield of system-channel messages to suppress. */
   system_channel_flags?: number;
+  /** Id of the rules channel, or `null` for none. */
   rules_channel_id?: string | null;
+  /** Id of the channel for Discord's community updates, or `null` for none. */
   public_updates_channel_id?: string | null;
+  /** The server's preferred locale, such as `en-US`. */
   preferred_locale?: string;
+  /** The server description, or `null` to clear it. */
   description?: string | null;
   /** The full list of mutable guild features (for example `COMMUNITY`); Discord ignores the ones it manages itself. */
   features?: string[];
 }
+/** A channel featured on a server's welcome screen. */
 export interface DiscordWelcomeChannel {
+  /** Id of the featured channel. */
   channel_id: string;
+  /** The blurb shown beside the channel. */
   description: string;
+  /** Id of a custom emoji shown beside it, or `null`. */
   emoji_id?: string | null;
+  /** Name of a Unicode emoji shown beside it, or `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. */
 export interface DiscordWelcomeScreen {
+  /** The server description shown on the screen, or `null`. */
   description: string | null;
+  /** The channels featured on the screen. */
   welcome_channels: DiscordWelcomeChannel[];
 }
+/** What `PATCH /guilds/{id}/welcome-screen` takes. */
 export interface ModifyWelcomeScreenInput {
+  /** Whether to turn the welcome screen on or off. */
   enabled?: boolean;
+  /** New welcome-screen description, or `null` to clear it. */
   description?: string | null;
+  /** The channels to feature on the welcome screen. */
   welcome_channels?: DiscordWelcomeChannel[];
 }
+/** A server emoji; `id` is `null` for a standard Unicode emoji. */
 export interface DiscordEmoji {
+  /** The emoji id, or `null` for a Unicode emoji. */
   id: string | null;
+  /** The emoji name (the Unicode character for a standard emoji), or `null`. */
   name: string | null;
+  /** Whether the emoji is animated. */
   animated?: boolean;
 }
+/** One answer a member can pick in an onboarding prompt. */
 export interface DiscordOnboardingOption {
+  /** The option id; absent when creating a new option. */
   id?: string;
+  /** The text of the option. */
   title: string;
+  /** A short explanation shown under the title. */
   description?: string | null;
+  /** Ids of the channels a member who picks this option is shown. */
   channel_ids?: string[];
+  /** Ids of the roles a member who picks this option is given. */
   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;
+  /** Name of a Unicode emoji, or of a custom emoji together with `emoji_id`. */
   emoji_name?: string | null;
+  /** Whether the custom emoji is animated. */
   emoji_animated?: boolean;
 }
+/** A question in the server's onboarding flow, with the options a member picks from. */
 export interface DiscordOnboardingPrompt {
+  /** The prompt id; absent when creating a new prompt. */
   id?: string;
   /** 0 multiple choice, 1 dropdown. */
   type: number;
+  /** The question text. */
   title: string;
+  /** Whether a member may pick only one option. */
   single_select: boolean;
+  /** Whether a member must answer. */
   required: boolean;
+  /** Whether the prompt appears during onboarding (otherwise only in Channels & Roles). */
   in_onboarding: boolean;
+  /** The answers a member can choose from. */
   options: DiscordOnboardingOption[];
 }
+/** A server's onboarding configuration, as `GET /guilds/{id}/onboarding` returns and `PUT` takes it. */
 export interface DiscordOnboarding {
+  /** The server id. */
   guild_id?: string;
+  /** The questions asked during onboarding. */
   prompts: DiscordOnboardingPrompt[];
+  /** Ids of the channels every new member is shown by default. */
   default_channel_ids: string[];
+  /** Whether onboarding is turned on. */
   enabled: boolean;
   /** 0 default, 1 advanced. */
   mode?: number;
 }
+/** A per-role or per-member override of a channel's permissions. */
 export interface DiscordPermissionOverwrite {
   /** Role or user id. */
   id: string;
@@ -153,92 +235,255 @@ export interface DiscordPermissionOverwrite {
   /** Bitfield of permissions to deny, as a string. */
   deny: string;
 }
+/** A channel or category in a server, as Discord returns it. */
 export interface DiscordChannel {
+  /** The channel id. */
   id: string;
+  /** The channel name. */
   name: string;
+  /** The channel type; see `ChannelType`. */
   type: number;
+  /** Id of the category the channel sits in, or `null` for none. */
   parent_id?: string | null;
+  /** The channel topic, or `null` when unset. */
   topic?: string | null;
+  /** The channel's sort position within its category or the server. */
   position?: number;
+  /** Permission overrides set on this channel. */
   permission_overwrites?: DiscordPermissionOverwrite[];
+  /** The tags a post in this forum channel can carry; present on forum channels only. */
+  available_tags?: DiscordForumTag[];
+}
+/** A tag a forum post can carry, with the emoji shown beside its name. */
+export interface DiscordForumTag {
+  /** The tag id. */
+  id: string;
+  /** The tag name, up to 20 characters. */
+  name: string;
+  /** Whether only members with Manage Threads can apply the tag. */
+  moderated: boolean;
+  /** Id of the tag's custom emoji, or `null` when it has none. */
+  emoji_id: string | null;
+  /** Name of the tag's Unicode emoji, or `null` when it has none. */
+  emoji_name: string | null;
+}
+/**
+ * A tag as sent when a forum is created or its tags are replaced. Send the whole list every time: Discord replaces
+ * the tags with it, and a tag keeps its id only when `id` is given.
+ */
+export interface ForumTagInput {
+  /** The id of a tag that already exists; leave it out to make a new one. */
+  id?: string;
+  /** The tag name, up to 20 characters. */
+  name: string;
+  /** Whether only members with Manage Threads can apply the tag. */
+  moderated?: boolean;
+  /** Id of a custom emoji for the tag. */
+  emoji_id?: string | null;
+  /** Name of a Unicode emoji for the tag, such as `💬`. */
+  emoji_name?: string | null;
+}
+/** What Discord says about a thread's state. */
+export interface DiscordThreadMetadata {
+  /** Whether the thread is archived (hidden from the active list until it is used again). */
+  archived: boolean;
+  /** Minutes of silence after which the thread archives: 60, 1440, 4320 or 10080. */
+  auto_archive_duration: number;
+  /** When the archived state last changed, as an ISO 8601 timestamp. */
+  archive_timestamp: string;
+  /** Whether only members with Manage Threads can unarchive and post in the thread. */
+  locked: boolean;
+}
+/** A thread, which in a forum channel is a post. */
+export interface DiscordThread extends DiscordChannel {
+  /** Id of the forum or text channel the thread belongs to. */
+  parent_id: string;
+  /** Id of the user who made the thread. */
+  owner_id?: string;
+  /** Ids of the forum tags applied to the post. */
+  applied_tags?: string[];
+  /** The thread's archive state. */
+  thread_metadata: DiscordThreadMetadata;
+}
+/** What `POST /channels/{id}/threads` takes to make a post in a forum channel. */
+export interface CreateForumPostInput {
+  /** The post's title, up to 100 characters. */
+  name: string;
+  /** Minutes of silence after which the post archives: 60, 1440, 4320 or 10080. */
+  auto_archive_duration?: number;
+  /** Ids of the forum tags to apply. */
+  applied_tags?: string[];
+  /** The post's first message. */
+  message: CreateMessageInput;
+}
+/** What making a forum post returns: the new thread, with the first message that opens it. */
+export interface DiscordForumPost extends DiscordThread {
+  /** The post's first message; its id is the thread's id. */
+  message?: DiscordMessage;
+}
+/** What `PATCH /channels/{id}` takes to change a thread. A field left out is left alone. */
+export interface ModifyThreadInput {
+  /** A new title, up to 100 characters. */
+  name?: string;
+  /** Ids of the forum tags to apply, replacing the current ones. */
+  applied_tags?: string[];
+  /** Whether the thread is archived. Writing to an archived thread unarchives it. */
+  archived?: boolean;
+  /** Whether only members with Manage Threads can unarchive and post in the thread. */
+  locked?: boolean;
+  /** Minutes of silence after which the thread archives: 60, 1440, 4320 or 10080. */
+  auto_archive_duration?: number;
+}
+/** One page of the archived threads of a channel. */
+export interface DiscordArchivedThreads {
+  /** The threads on this page, newest archived first. */
+  threads: DiscordThread[];
+  /** Whether more archived threads remain after this page. */
+  has_more: boolean;
+}
+/** What `GET /channels/{id}/threads/archived/public` takes. */
+export interface ListArchivedThreadsInput {
+  /** Only threads archived before this ISO 8601 timestamp. */
+  before?: string;
+  /** The page size, 1 to 100. Defaults to 100. */
+  limit?: number;
 }
+/** What `PATCH /channels/{id}/messages/{id}` takes. A field left out is left alone. */
+export interface EditMessageInput {
+  /** The new message text. */
+  content: string;
+  /** Defaults to no mentions, so editing in a pasted `@everyone` cannot ping anyone. */
+  allowed_mentions?: CreateMessageInput["allowed_mentions"];
+}
+/** What `POST /guilds/{id}/channels` takes. */
 export interface CreateChannelInput {
+  /** The channel name. */
   name: string;
+  /** The channel type; see `ChannelType`. Discord creates a text channel when omitted. */
   type?: number;
+  /** The channel topic. */
   topic?: string;
+  /** Id of the category to create the channel in. */
   parent_id?: string;
+  /** Permission overrides to set on the new channel. */
   permission_overwrites?: DiscordPermissionOverwrite[];
+  /** The tags of a forum channel (`ChannelType.Forum`). */
+  available_tags?: ForumTagInput[];
 }
 /** `null` clears `topic` or detaches the channel from its category. */
 export interface ModifyChannelInput {
+  /** A new channel name. */
   name?: string;
+  /** A new topic. */
   topic?: string | null;
+  /** Id of the category to move the channel into. */
   parent_id?: string | null;
+  /** The full list of permission overrides, replacing the existing ones. */
   permission_overwrites?: DiscordPermissionOverwrite[];
+  /** The full list of a forum channel's tags, replacing the existing ones; give a tag's `id` to keep it. */
+  available_tags?: ForumTagInput[];
 }
 /** A member of a server. Only what provisioning needs: who they are and which roles they hold. */
 export interface DiscordGuildMember {
+  /** The member's account; Discord leaves it out in some message contexts. */
   user?: {
+    /** The user id. */
     id: string;
+    /** The account's username. */
     username?: string;
   };
   /** Ids of the roles the member holds. */
   roles: string[];
+  /** The member's nickname in the server, or `null` when none is set. */
   nick?: string | null;
 }
+/** A role in a server, as Discord returns it. */
 export interface DiscordRole {
+  /** The role id. */
   id: string;
+  /** The role name. */
   name: string;
+  /** The role colour as an integer RGB value; `0` means no colour. */
   color: number;
+  /** Whether anyone can @mention the role. */
   mentionable: boolean;
+  /** Whether members with the role are listed separately in the member list. */
   hoist?: boolean;
   /** Bitfield of permissions, as a string. */
   permissions?: string;
+  /** Whether an integration (such as a bot) manages the role. */
   managed?: boolean;
+  /** The role's position in the role hierarchy. */
   position?: number;
 }
+/** Role fields `PATCH /guilds/{id}/roles/{id}` can change; a field left out is left alone. */
 export interface ModifyRoleInput {
+  /** A new role name. */
   name?: string;
+  /** A new colour as an integer RGB value. */
   color?: number;
+  /** Whether to list the role's members separately. */
   hoist?: boolean;
+  /** Whether anyone can @mention the role. */
   mentionable?: boolean;
   /** Bitfield of permissions, as a string. */
   permissions?: string;
 }
+/** What `POST /guilds/{id}/roles` takes. */
 export interface CreateRoleInput {
+  /** The role name. */
   name: string;
+  /** The colour as an integer RGB value. */
   color?: number;
+  /** Whether anyone can @mention the role. */
   mentionable?: boolean;
+  /** Whether to list the role's members separately. */
   hoist?: boolean;
   /** Bitfield of permissions, as a string. */
   permissions?: string;
 }
+/** A webhook attached to a channel, as the bot API returns it. */
 export interface DiscordChannelWebhook {
+  /** The webhook id. */
   id: string;
+  /** The webhook name, or `null` when unset. */
   name: string | null;
   /** The avatar hash, or `null` for the default one. */
   avatar?: string | null;
+  /** Id of the channel the webhook posts to. */
   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;
 }
+/** What `POST /channels/{id}/messages` takes. */
 export interface CreateMessageInput {
+  /** The message text. */
   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;
+  /** Turns on the nonce de-duplication for `nonce`. */
   enforce_nonce?: boolean;
+  /** Message flags; see `MessageFlag`. */
+  flags?: number;
   /** Defaults to no mentions, so a pasted `@everyone` cannot ping anyone. */
   allowed_mentions?: {
+    /** Which mention types Discord may resolve into pings. */
     parse?: Array<"roles" | "users" | "everyone">;
+    /** Ids of the roles that may be pinged. */
     roles?: string[];
+    /** Ids of the users that may be pinged. */
     users?: string[];
   };
 }
+/** A message that was posted, as Discord returns it. */
 export interface DiscordMessage {
+  /** The message id. */
   id: string;
+  /** Id of the channel the message is in. */
   channel_id: string;
+  /** The message text. */
   content: string;
 }
 /** How the bot is added to a server or an account. */
@@ -253,17 +498,26 @@ export interface DiscordInstallParams {
  * that Discord has not verified; once verified, the plain ones take over and the toggle is Discord's to change.
  */
 export declare const ApplicationFlag: {
+  /** Application may receive presence updates (verified apps). */
   readonly GatewayPresence: number;
+  /** The privileged presence intent toggle for an unverified app. */
   readonly GatewayPresenceLimited: number;
+  /** Application may receive server-member events and the member list (verified apps). */
   readonly GatewayGuildMembers: number;
+  /** The privileged server-members intent toggle for an unverified app. */
   readonly GatewayGuildMembersLimited: number;
+  /** Application may read message content (verified apps). */
   readonly GatewayMessageContent: number;
+  /** The privileged message-content intent toggle for an unverified app. */
   readonly GatewayMessageContentLimited: number;
 };
 /** The bot's own application, as `GET /applications/@me` returns it. Fields Discord leaves out are absent or null. */
 export interface DiscordApplication {
+  /** The application id. */
   id: string;
+  /** The application name. */
   name: string;
+  /** The description shown on the application's page. */
   description?: string | null;
   /** Up to five short labels shown on the application's page. */
   tags?: string[];
@@ -271,13 +525,19 @@ export interface DiscordApplication {
   install_params?: DiscordInstallParams;
   /** Used instead of the default install link when set. */
   custom_install_url?: string | null;
+  /** URL Discord uses for linked-role verification. */
   role_connections_verification_url?: string | null;
+  /** URL of the application's terms of service. */
   terms_of_service_url?: string | null;
+  /** URL of the application's privacy policy. */
   privacy_policy_url?: string | null;
+  /** URL Discord sends interaction events to. */
   interactions_endpoint_url?: string | null;
   /** Whether anyone can add the bot (`true`) or only its owner. */
   bot_public?: boolean;
+  /** Whether the bot is only added after the full OAuth2 code grant. */
   bot_require_code_grant?: boolean;
+  /** The application flags bitfield; see `ApplicationFlag`. */
   flags?: number;
   /**
    * The OAuth2 redirect URIs registered on the application. Read-only here: Discord accepts a write to this
@@ -287,13 +547,21 @@ export interface DiscordApplication {
 }
 /** What `PATCH /applications/@me` takes; a field left out is left alone, and `null` clears the ones that can be cleared. */
 export interface ModifyApplicationInput {
+  /** A new description. */
   description?: string;
+  /** The new tags (at most five). */
   tags?: string[];
+  /** The new default install link scopes and permissions. */
   install_params?: DiscordInstallParams;
+  /** A custom install URL, or `null` to use the default link. */
   custom_install_url?: string | null;
+  /** The linked-role verification URL, or `null` to clear it. */
   role_connections_verification_url?: string | null;
+  /** The terms of service URL, or `null` to clear it. */
   terms_of_service_url?: string | null;
+  /** The privacy policy URL, or `null` to clear it. */
   privacy_policy_url?: string | null;
+  /** The interactions endpoint URL, or `null` to clear it. */
   interactions_endpoint_url?: string | null;
   /**
    * The whole flags value. Discord keeps only the bits an app may change (the `*Limited` privileged-intent
@@ -301,22 +569,29 @@ export interface ModifyApplicationInput {
    */
   flags?: number;
 }
+/** What `PATCH /webhooks/{id}` takes; a field left out is left alone. */
 export interface ModifyWebhookInput {
+  /** A new webhook name. */
   name?: string;
   /** A data URI (`data:image/png;base64,...`); `null` clears it. */
   avatar?: string | null;
 }
 /** What `POST /guilds` takes. Only a bot in fewer than ten servers may create one, and it becomes the owner. */
 export interface CreateGuildInput {
+  /** The server name. */
   name: string;
   /** A data URI (`data:image/png;base64,...`). */
   icon?: string;
+  /** Verification level, using the same values as `DiscordGuild.verification_level`. */
   verification_level?: number;
+  /** Default notification setting, using the same values as `DiscordGuild.default_message_notifications`. */
   default_message_notifications?: number;
+  /** Content filter level, using the same values as `DiscordGuild.explicit_content_filter`. */
   explicit_content_filter?: number;
 }
 /** Page options for `guilds.members`; Discord caps `limit` at 1000. */
 export interface ListMembersInput {
+  /** How many members to return; Discord caps it at 1000. */
   limit?: number;
   /** Return members after this user id. */
   after?: string;
@@ -325,29 +600,43 @@ export interface DiscordEmoji {
   id: string | null;
   name: string | null;
   animated?: boolean;
+  /** Whether the emoji can be used (it may be unavailable when the server lost a boost level). */
   available?: boolean;
 }
+/** What `POST /channels/{id}/invites` takes. */
 export interface CreateInviteInput {
   /** Seconds until it expires; `0` never. Discord's default is 86400. */
   max_age?: number;
   /** Uses before it is revoked; `0` unlimited. */
   max_uses?: number;
+  /** Whether the invite grants temporary membership. */
   temporary?: boolean;
+  /** Whether to always create a new invite instead of reusing a similar one. */
   unique?: boolean;
 }
+/** A server invite, as Discord returns it. */
 export interface DiscordInvite {
+  /** The invite code, the part after `discord.gg/`. */
   code: string;
+  /** Id of the channel the invite leads to. */
   channel_id?: string;
+  /** How many times the invite has been used. */
   uses?: number;
 }
 /** A message listed back from a channel, with who wrote it. */
 export interface DiscordChannelMessage extends DiscordMessage {
+  /** Who wrote the message; absent when Discord omits it. */
   author?: {
+    /** The author's user id. */
     id: string;
+    /** The author's username. */
     username?: string;
+    /** Whether the author is a bot. */
     bot?: boolean;
   };
+  /** Id of the webhook that posted the message, when one did. */
   webhook_id?: string;
+  /** Whether the message is pinned in its channel. */
   pinned?: boolean;
 }
 /**
@@ -416,6 +705,10 @@ export declare function createDiscordBotClient(opts: DiscordBotClientOptions): {
     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>;
+    /** `GET /channels/:id/messages/:id` — one message, e.g. the first message of a forum post (its id is the post's). */
+    message: (channelId: string, messageId: string) => Promise<DiscordChannelMessage>;
+    /** `PATCH /channels/:id/messages/:id` — a message this bot posted. Mentions are off unless `allowed_mentions` asks for them. */
+    editMessage: (channelId: string, messageId: string, body: EditMessageInput) => Promise<DiscordMessage>;
     /** `POST /channels/:id/invites` — a join link for the server, e.g. to hand over a newly created one. */
     createInvite: (channelId: string, body?: CreateInviteInput) => Promise<DiscordInvite>;
     /** `GET /channels/:id/messages` — the newest messages first, to read a post back. */
@@ -427,6 +720,24 @@ export declare function createDiscordBotClient(opts: DiscordBotClientOptions): {
       name: string;
     }) => Promise<DiscordChannelWebhook>;
   };
+  threads: {
+    /**
+     * `POST /channels/:id/threads` in a forum channel — a new post with its first message. Not idempotent: look
+     * the post up (`inChannel`) before retrying. Mentions in the first message are off unless asked for.
+     */
+    createForumPost: (channelId: string, body: CreateForumPostInput) => Promise<DiscordForumPost>;
+    /** `PATCH /channels/:id` on a thread — its title, tags, archived or locked state. Writing to an archived post unarchives it. */
+    modify: (threadId: string, body: ModifyThreadInput) => Promise<DiscordThread>;
+    /** `GET /guilds/:id/threads/active` — every active thread in the server, across channels. */
+    active: (guildId: string) => Promise<DiscordThread[]>;
+    /** `GET /channels/:id/threads/archived/public` — one page of a channel's archived threads, newest archived first. */
+    archived: (channelId: string, opts?: ListArchivedThreadsInput) => Promise<DiscordArchivedThreads>;
+    /**
+     * Every post in a forum channel, active and archived: Discord hides a post that has been quiet for a while, so
+     * a lookup that read only the active ones would miss it and make it again.
+     */
+    inChannel: (guildId: string, channelId: string) => Promise<DiscordThread[]>;
+  };
   application: {
     /** `GET /applications/@me` — the bot's own application: description, tags, install settings, URLs. */
     get: () => Promise<DiscordApplication>;
@@ -441,6 +752,7 @@ export declare function createDiscordBotClient(opts: DiscordBotClientOptions): {
     delete: (webhookId: string) => Promise<void>;
   };
 };
+/** The bot-token client returned by `createDiscordBotClient`, with its resource groups (guilds, channels, roles, webhooks, messages and so on). */
 export type DiscordBotClient = ReturnType<typeof createDiscordBotClient>;
 /**
  * Discord permission bits, by the names the Discord docs use. Permissions travel as
@@ -449,62 +761,114 @@ export type DiscordBotClient = ReturnType<typeof createDiscordBotClient>;
  * `permissions` cannot set them by name.
  */
 export declare const Permission: {
+  /** Create invites to the server. */
   readonly CreateInstantInvite: bigint;
+  /** Kick members. */
   readonly KickMembers: bigint;
+  /** Ban members. */
   readonly BanMembers: bigint;
+  /** Administrator: all permissions, and bypasses channel overrides. */
   readonly Administrator: bigint;
+  /** Create, edit and delete channels. */
   readonly ManageChannels: bigint;
+  /** Change server settings. */
   readonly ManageGuild: bigint;
+  /** Add new reactions to messages. */
   readonly AddReactions: bigint;
+  /** View the audit log. */
   readonly ViewAuditLog: bigint;
+  /** Use priority speaker in voice channels. */
   readonly PrioritySpeaker: bigint;
+  /** Go live (stream) in voice channels. */
   readonly Stream: bigint;
+  /** View channels (and read their messages). */
   readonly ViewChannel: bigint;
+  /** Send messages in text channels. */
   readonly SendMessages: bigint;
+  /** Send text-to-speech messages. */
   readonly SendTtsMessages: bigint;
+  /** Delete other members' messages and pin messages. */
   readonly ManageMessages: bigint;
+  /** Have links in messages embed. */
   readonly EmbedLinks: bigint;
+  /** Upload files and media. */
   readonly AttachFiles: bigint;
+  /** Read message history. */
   readonly ReadMessageHistory: bigint;
+  /** Mention @everyone, @here and all roles. */
   readonly MentionEveryone: bigint;
+  /** Use emojis from other servers. */
   readonly UseExternalEmojis: bigint;
+  /** View server insights. */
   readonly ViewGuildInsights: bigint;
+  /** Join voice channels. */
   readonly Connect: bigint;
+  /** Speak in voice channels. */
   readonly Speak: bigint;
+  /** Mute other members in voice channels. */
   readonly MuteMembers: bigint;
+  /** Deafen other members in voice channels. */
   readonly DeafenMembers: bigint;
+  /** Move members between voice channels. */
   readonly MoveMembers: bigint;
+  /** Use voice activity detection instead of push-to-talk. */
   readonly UseVoiceActivity: bigint;
+  /** Change one's own nickname. */
   readonly ChangeNickname: bigint;
+  /** Change other members' nicknames. */
   readonly ManageNicknames: bigint;
+  /** Create, edit and delete roles lower than the member's own. */
   readonly ManageRoles: bigint;
+  /** Create, edit and delete webhooks. */
   readonly ManageWebhooks: bigint;
+  /** Edit and delete emojis, stickers and soundboard sounds. */
   readonly ManageGuildExpressions: bigint;
+  /** Use application commands (slash commands). */
   readonly UseApplicationCommands: bigint;
+  /** Request to speak in stage channels. */
   readonly RequestToSpeak: bigint;
+  /** Edit and delete scheduled events. */
   readonly ManageEvents: bigint;
+  /** Manage and delete threads. */
   readonly ManageThreads: bigint;
+  /** Create public threads. */
   readonly CreatePublicThreads: bigint;
+  /** Create private threads. */
   readonly CreatePrivateThreads: bigint;
+  /** Use stickers from other servers. */
   readonly UseExternalStickers: bigint;
+  /** Send messages in threads. */
   readonly SendMessagesInThreads: bigint;
+  /** Start activities in voice channels. */
   readonly UseEmbeddedActivities: bigint;
+  /** Time out members. */
   readonly ModerateMembers: bigint;
+  /** View creator monetization analytics. */
   readonly ViewCreatorMonetizationAnalytics: bigint;
+  /** Use soundboard sounds. */
   readonly UseSoundboard: bigint;
+  /** Create emojis, stickers and soundboard sounds. */
   readonly CreateGuildExpressions: bigint;
+  /** Create scheduled events. */
   readonly CreateEvents: bigint;
+  /** Use soundboard sounds from other servers. */
   readonly UseExternalSounds: bigint;
+  /** Send voice messages. */
   readonly SendVoiceMessages: bigint;
+  /** Send polls. */
   readonly SendPolls: bigint;
+  /** Use apps that are not installed in the server. */
   readonly UseExternalApps: bigint;
+  /** Pin and unpin messages. */
   readonly PinMessages: bigint;
 };
+/** The name of one entry in `Permission`. */
 export type PermissionName = keyof typeof Permission;
 /** The decimal-string bitfield Discord wants for the named permissions (`"0"` for none). */
 export declare function permissions(names: readonly PermissionName[]): string;
 /** The permission names set in a bitfield, in declaration order (unknown bits are ignored). */
 export declare function permissionNames(bitfield: string): PermissionName[];
+/** Options for `createDiscordOAuthClient`. */
 export interface DiscordOAuthClientOptions {
   /** The application's client id (the same as its application id). Not a secret. */
   clientId: string;
@@ -523,11 +887,15 @@ export interface DiscordOAuthClientOptions {
 }
 /** What a member's token may do: `identify` reads who they are, `connections` reads their linked accounts. */
 export type DiscordOAuthScope = "identify" | "connections";
+/** The token Discord returns from the OAuth2 token endpoint. */
 export interface DiscordOAuthToken {
+  /** The access token to send as a bearer. */
   access_token: string;
+  /** The token type, `Bearer`. */
   token_type: string;
   /** Seconds until `access_token` stops working. */
   expires_in: number;
+  /** The token that can be exchanged for a new access token. */
   refresh_token?: string;
   /** The scopes granted, space separated. */
   scope: string;
@@ -542,12 +910,16 @@ export interface DiscordConnection {
   type: string;
   /** Whether Discord confirmed the member owns the account. */
   verified: boolean;
+  /** Discord's visibility code: 0 only the member, 1 everyone. */
   visibility?: number;
 }
 /** The member who signed in, as `GET /users/@me` returns it with their token. */
 export interface DiscordOAuthUser {
+  /** The Discord user id. */
   id: string;
+  /** The account's username. */
   username: string;
+  /** The display name, or `null` when the member has none. */
   global_name?: string | null;
 }
 /**
@@ -580,6 +952,7 @@ export declare function createDiscordOAuthClient(opts: DiscordOAuthClientOptions
   /** `GET /users/@me/connections` as the member (needs `connections`). */
   connections: (accessToken: string) => Promise<DiscordConnection[]>;
 };
+/** The member-OAuth client returned by `createDiscordOAuthClient`. */
 export type DiscordOAuthClient = ReturnType<typeof createDiscordOAuthClient>;
 /**
  * The verified connection of one service, or `undefined`. Unverified ones are ignored: anyone can type a
@@ -603,6 +976,7 @@ export declare function signOAuthState(secret: string, opts?: {
 export declare function verifyOAuthState(secret: string, state: string, opts?: {
   now?: number;
 }): boolean;
+/** Builds the webhook client: a `webhooks` group that reads, posts to and deletes messages from a webhook by its id and token. */
 export declare function createDiscordClient(opts?: DiscordClientOptions): {
   webhooks: {
     get: (id: string, token: string) => Promise<DiscordWebhookInfo>;
@@ -613,5 +987,6 @@ export declare function createDiscordClient(opts?: DiscordClientOptions): {
     deleteMessage: (id: string, token: string, messageId: string) => Promise<void>;
   };
 };
+/** The client `createDiscordClient` returns. */
 export type DiscordClient = ReturnType<typeof createDiscordClient>;
 export type { DiscordClientOptions, DiscordWebhookInfo };

package/dist/index.mjs

@@ -81,6 +81,8 @@ const DEFAULT_MAX_RETRIES = 3;
 const MAX_RETRY_WAIT_MS = 1e4;
 /** A guard on `membersWithRole`, so a runaway cursor cannot loop forever. */
 const MAX_MEMBER_PAGES = 50;
+/** A guard on `threads.inChannel`, so a runaway `before` cursor cannot loop forever. */
+const MAX_THREAD_PAGES = 50;
 /** Discord ids are snowflakes; anything else would be spliced into a URL path. */
 function id(value) {
 	if (!/^\d{1,20}$/.test(value)) throw new Error(`invalid Discord id: ${JSON.stringify(value)}`);
@@ -93,6 +95,22 @@ function bodyIds(...values) {
 		for (const one of typeof value === "string" ? [value] : value) id(one);
 	}
 }
+/**
+* A message body with its mention ids checked and mentions switched off unless asked for. The default is applied
+* after the spread, so an explicit `allowed_mentions: undefined` still means "no mentions".
+*/
+function withMentionsOff(body) {
+	bodyIds(body.allowed_mentions?.roles, body.allowed_mentions?.users);
+	return {
+		...body,
+		allowed_mentions: body.allowed_mentions ?? { parse: [] }
+	};
+}
+/** An ISO 8601 timestamp that travels in a query, so a malformed one fails here and not at Discord. */
+function timestamp(value) {
+	if (Number.isNaN(Date.parse(value))) throw new Error(`invalid timestamp: ${JSON.stringify(value)}`);
+	return value;
+}
 /** 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"));
@@ -279,16 +297,17 @@ function createDiscordBotClient(opts) {
 			}),
 			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: [] }
-					}
-				});
-			},
+			createMessage: (channelId, body) => rest.request(`/channels/${id(channelId)}/messages`, {
+				method: "POST",
+				body: withMentionsOff(body)
+			}),
+			/** `GET /channels/:id/messages/:id` — one message, e.g. the first message of a forum post (its id is the post's). */
+			message: (channelId, messageId) => rest.request(`/channels/${id(channelId)}/messages/${id(messageId)}`),
+			/** `PATCH /channels/:id/messages/:id` — a message this bot posted. Mentions are off unless `allowed_mentions` asks for them. */
+			editMessage: (channelId, messageId, body) => rest.request(`/channels/${id(channelId)}/messages/${id(messageId)}`, {
+				method: "PATCH",
+				body: withMentionsOff(body)
+			}),
 			/** `POST /channels/:id/invites` — a join link for the server, e.g. to hand over a newly created one. */
 			createInvite: (channelId, body = {}) => rest.request(`/channels/${id(channelId)}/invites`, {
 				method: "POST",
@@ -310,6 +329,59 @@ function createDiscordBotClient(opts) {
 				body
 			}))
 		},
+		threads: {
+			/**
+			* `POST /channels/:id/threads` in a forum channel — a new post with its first message. Not idempotent: look
+			* the post up (`inChannel`) before retrying. Mentions in the first message are off unless asked for.
+			*/
+			createForumPost: (channelId, body) => {
+				bodyIds(body.applied_tags);
+				return rest.request(`/channels/${id(channelId)}/threads`, {
+					method: "POST",
+					body: {
+						...body,
+						message: withMentionsOff(body.message)
+					}
+				});
+			},
+			/** `PATCH /channels/:id` on a thread — its title, tags, archived or locked state. Writing to an archived post unarchives it. */
+			modify: (threadId, body) => {
+				bodyIds(body.applied_tags);
+				return rest.request(`/channels/${id(threadId)}`, {
+					method: "PATCH",
+					body
+				});
+			},
+			/** `GET /guilds/:id/threads/active` — every active thread in the server, across channels. */
+			active: async (guildId) => (await rest.request(`/guilds/${id(guildId)}/threads/active`)).threads,
+			/** `GET /channels/:id/threads/archived/public` — one page of a channel's archived threads, newest archived first. */
+			archived: (channelId, opts = {}) => {
+				const query = { limit: String(Math.min(Math.max(opts.limit ?? 100, 1), 100)) };
+				if (opts.before !== void 0) query.before = timestamp(opts.before);
+				return rest.request(`/channels/${id(channelId)}/threads/archived/public`, { query });
+			},
+			/**
+			* Every post in a forum channel, active and archived: Discord hides a post that has been quiet for a while, so
+			* a lookup that read only the active ones would miss it and make it again.
+			*/
+			inChannel: async (guildId, channelId) => {
+				const parent = id(channelId);
+				const { threads } = await rest.request(`/guilds/${id(guildId)}/threads/active`);
+				const found = threads.filter((t) => t.parent_id === parent);
+				let before;
+				for (let page = 0; page < MAX_THREAD_PAGES; page++) {
+					const batch = await rest.request(`/channels/${parent}/threads/archived/public`, { query: {
+						limit: "100",
+						...before === void 0 ? {} : { before: timestamp(before) }
+					} });
+					found.push(...batch.threads);
+					const last = batch.threads[batch.threads.length - 1];
+					if (!batch.has_more || last === void 0) return found;
+					before = last.thread_metadata.archive_timestamp;
+				}
+				throw new Error(`more than 5000 archived threads; refusing to read them all`);
+			}
+		},
 		application: {
 			/** `GET /applications/@me` — the bot's own application: description, tags, install settings, URLs. */
 			get: () => rest.request("/applications/@me"),
@@ -344,21 +416,35 @@ function createDiscordBotClient(opts) {
 // src/bot/bot.type.ts
 /** Discord channel `type` values this client creates or reads. */
 const ChannelType = {
+	/** A text channel. */
 	Text: 0,
+	/** A category that groups channels. */
 	Category: 4,
+	/** An announcement channel. */
 	Announcement: 5,
+	/** A forum channel. */
 	Forum: 15
 };
+/** Bits of a message's `flags` that a bot may set when it posts. */
+const MessageFlag = { 
+/** Posts without notifying anyone, as a backfill of many messages should. */
+SuppressNotifications: 4096 };
 /**
 * Bits of the application's `flags`. The `*Limited` ones are the portal's privileged-intent toggles for an app
 * that Discord has not verified; once verified, the plain ones take over and the toggle is Discord's to change.
 */
 const ApplicationFlag = {
+	/** Application may receive presence updates (verified apps). */
 	GatewayPresence: 4096,
+	/** The privileged presence intent toggle for an unverified app. */
 	GatewayPresenceLimited: 8192,
+	/** Application may receive server-member events and the member list (verified apps). */
 	GatewayGuildMembers: 16384,
+	/** The privileged server-members intent toggle for an unverified app. */
 	GatewayGuildMembersLimited: 32768,
+	/** Application may read message content (verified apps). */
 	GatewayMessageContent: 1 << 18,
+	/** The privileged message-content intent toggle for an unverified app. */
 	GatewayMessageContentLimited: 1 << 19
 };
 // src/bot/permissions.ts
@@ -369,55 +455,105 @@ const ApplicationFlag = {
 * `permissions` cannot set them by name.
 */
 const Permission = {
+	/** Create invites to the server. */
 	CreateInstantInvite: 1n << 0n,
+	/** Kick members. */
 	KickMembers: 1n << 1n,
+	/** Ban members. */
 	BanMembers: 1n << 2n,
+	/** Administrator: all permissions, and bypasses channel overrides. */
 	Administrator: 1n << 3n,
+	/** Create, edit and delete channels. */
 	ManageChannels: 1n << 4n,
+	/** Change server settings. */
 	ManageGuild: 1n << 5n,
+	/** Add new reactions to messages. */
 	AddReactions: 1n << 6n,
+	/** View the audit log. */
 	ViewAuditLog: 1n << 7n,
+	/** Use priority speaker in voice channels. */
 	PrioritySpeaker: 1n << 8n,
+	/** Go live (stream) in voice channels. */
 	Stream: 1n << 9n,
+	/** View channels (and read their messages). */
 	ViewChannel: 1n << 10n,
+	/** Send messages in text channels. */
 	SendMessages: 1n << 11n,
+	/** Send text-to-speech messages. */
 	SendTtsMessages: 1n << 12n,
+	/** Delete other members' messages and pin messages. */
 	ManageMessages: 1n << 13n,
+	/** Have links in messages embed. */
 	EmbedLinks: 1n << 14n,
+	/** Upload files and media. */
 	AttachFiles: 1n << 15n,
+	/** Read message history. */
 	ReadMessageHistory: 1n << 16n,
+	/** Mention @everyone, @here and all roles. */
 	MentionEveryone: 1n << 17n,
+	/** Use emojis from other servers. */
 	UseExternalEmojis: 1n << 18n,
+	/** View server insights. */
 	ViewGuildInsights: 1n << 19n,
+	/** Join voice channels. */
 	Connect: 1n << 20n,
+	/** Speak in voice channels. */
 	Speak: 1n << 21n,
+	/** Mute other members in voice channels. */
 	MuteMembers: 1n << 22n,
+	/** Deafen other members in voice channels. */
 	DeafenMembers: 1n << 23n,
+	/** Move members between voice channels. */
 	MoveMembers: 1n << 24n,
+	/** Use voice activity detection instead of push-to-talk. */
 	UseVoiceActivity: 1n << 25n,
+	/** Change one's own nickname. */
 	ChangeNickname: 1n << 26n,
+	/** Change other members' nicknames. */
 	ManageNicknames: 1n << 27n,
+	/** Create, edit and delete roles lower than the member's own. */
 	ManageRoles: 1n << 28n,
+	/** Create, edit and delete webhooks. */
 	ManageWebhooks: 1n << 29n,
+	/** Edit and delete emojis, stickers and soundboard sounds. */
 	ManageGuildExpressions: 1n << 30n,
+	/** Use application commands (slash commands). */
 	UseApplicationCommands: 1n << 31n,
+	/** Request to speak in stage channels. */
 	RequestToSpeak: 1n << 32n,
+	/** Edit and delete scheduled events. */
 	ManageEvents: 1n << 33n,
+	/** Manage and delete threads. */
 	ManageThreads: 1n << 34n,
+	/** Create public threads. */
 	CreatePublicThreads: 1n << 35n,
+	/** Create private threads. */
 	CreatePrivateThreads: 1n << 36n,
+	/** Use stickers from other servers. */
 	UseExternalStickers: 1n << 37n,
+	/** Send messages in threads. */
 	SendMessagesInThreads: 1n << 38n,
+	/** Start activities in voice channels. */
 	UseEmbeddedActivities: 1n << 39n,
+	/** Time out members. */
 	ModerateMembers: 1n << 40n,
+	/** View creator monetization analytics. */
 	ViewCreatorMonetizationAnalytics: 1n << 41n,
+	/** Use soundboard sounds. */
 	UseSoundboard: 1n << 42n,
+	/** Create emojis, stickers and soundboard sounds. */
 	CreateGuildExpressions: 1n << 43n,
+	/** Create scheduled events. */
 	CreateEvents: 1n << 44n,
+	/** Use soundboard sounds from other servers. */
 	UseExternalSounds: 1n << 45n,
+	/** Send voice messages. */
 	SendVoiceMessages: 1n << 46n,
+	/** Send polls. */
 	SendPolls: 1n << 49n,
+	/** Use apps that are not installed in the server. */
 	UseExternalApps: 1n << 50n,
+	/** Pin and unpin messages. */
 	PinMessages: 1n << 51n
 };
 /** The decimal-string bitfield Discord wants for the named permissions (`"0"` for none). */
@@ -561,7 +697,8 @@ function verifyOAuthState(secret, state, opts = {}) {
 	return Number(expires) >= Math.floor((opts.now ?? Date.now()) / 1e3);
 }
 // src/index.ts
+/** Builds the webhook client: a `webhooks` group that reads, posts to and deletes messages from a webhook by its id and token. */
 function createDiscordClient(opts = {}) {
 	return { webhooks: webhooks(opts.baseUrl ?? "https://discord.com/api/v10", opts.fetch ?? globalThis.fetch) };
 }
-export { ApplicationFlag, ChannelType, DEFAULT_STATE_TTL_SECONDS, Permission, createDiscordBotClient, createDiscordClient, createDiscordOAuthClient, findVerifiedConnection, parseWebhookUrl, permissionNames, permissions, signOAuthState, verifyOAuthState };
+export { ApplicationFlag, ChannelType, DEFAULT_STATE_TTL_SECONDS, MessageFlag, Permission, createDiscordBotClient, createDiscordClient, createDiscordOAuthClient, findVerifiedConnection, parseWebhookUrl, permissionNames, permissions, signOAuthState, verifyOAuthState };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/discord-client",
-  "version": "1.57.1-alpha.2",
+  "version": "1.58.0-alpha.10",
   "description": "A TypeScript client for the Discord webhooks API",
   "keywords": [
     "discord",
@@ -32,22 +32,22 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/http-client": "^1.57.1-alpha.2"
+    "@theholocron/http-client": "^1.58.0-alpha.10"
   },
   "devDependencies": {
     "@types/node": "^26",
     "@vitest/coverage-v8": "^5.0.5",
-    "@vitest/eslint-plugin": "^1.6.27",
-    "eslint": "^10.8.1",
-    "eslint-plugin-n": "^18.3.0",
-    "globals": "^17.11.0",
-    "tsdown": "^0.23.3",
+    "@vitest/eslint-plugin": "^1.6.28",
+    "eslint": "^10.14.0",
+    "eslint-plugin-n": "^18.5.0",
+    "globals": "^17.14.0",
+    "tsdown": "^0.23.4",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
-    "@theholocron/eslint-config": "^8.9.0-alpha.3",
-    "@theholocron/tsconfig": "^8.9.0-alpha.3",
-    "@theholocron/tsdown-config": "^8.9.0-alpha.3",
-    "@theholocron/vitest-config": "^8.9.0-alpha.3"
+    "@theholocron/tsconfig": "^8.9.0-alpha.8",
+    "@theholocron/eslint-config": "^8.9.0-alpha.8",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.8",
+    "@theholocron/vitest-config": "^8.9.0-alpha.8"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -56,10 +56,10 @@
     "access": "public"
   },
   "scripts": {
-    "delivery.build": "tsdown && node ../scripts/check-bundle-size.mjs",
-    "sourceQuality.staticAnalysis": "eslint .",
+    "build": "tsdown && node ../scripts/check-bundle-size.mjs",
+    "lint:code": "eslint .",
+    "test:unit": "vitest run --coverage",
     "test:watch": "vitest",
-    "verification.typeSafety": "tsc --noEmit",
-    "verification.unitTests": "vitest run"
+    "typecheck": "tsc --noEmit"
   }
 }