@theholocron/discord-client 1.58.0-alpha.4 → 1.58.0-alpha.8

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

@@ -51,6 +51,11 @@ export declare const ChannelType: {
   /** 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. */
@@ -246,6 +251,109 @@ export interface DiscordChannel {
   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 {
@@ -259,6 +367,8 @@ export interface CreateChannelInput {
   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 {
@@ -270,6 +380,8 @@ export interface ModifyChannelInput {
   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 {
@@ -353,6 +465,8 @@ export interface CreateMessageInput {
   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. */
@@ -591,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. */
@@ -602,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>;

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"),
@@ -353,6 +425,10 @@ const ChannelType = {
 	/** 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.
@@ -625,4 +701,4 @@ function verifyOAuthState(secret, state, opts = {}) {
 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.58.0-alpha.4",
+  "version": "1.58.0-alpha.8",
   "description": "A TypeScript client for the Discord webhooks API",
   "keywords": [
     "discord",
@@ -32,22 +32,22 @@
     "dist"
   ],
   "dependencies": {
-    "@theholocron/http-client": "^1.58.0-alpha.4"
+    "@theholocron/http-client": "^1.58.0-alpha.8"
   },
   "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/tsdown-config": "^8.9.0-alpha.5",
-    "@theholocron/tsconfig": "^8.9.0-alpha.5",
-    "@theholocron/eslint-config": "^8.9.0-alpha.5",
-    "@theholocron/vitest-config": "^8.9.0-alpha.5"
+    "@theholocron/eslint-config": "^8.9.0-alpha.8",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.8",
+    "@theholocron/tsconfig": "^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"
   }
 }