@theholocron/discord-client 1.45.0 → 1.46.0

package/README.md

@@ -99,13 +99,13 @@ 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.application` | `get`, `modify` (the bot's own application: description, tags, install settings, URLs)                                                                      |
-| `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`                                                                                                                           |
+| Resource             | Methods                                                                                                                                                                                                                                                                |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client.users`       | `me()` — `GET /users/@me`, a cheap token check; `get(id)` — a user's name                                                                                                                                                                                              |
+| `client.application` | `get`, `modify` (the bot's own application: description, tags, install settings, URLs)                                                                                                                                                                                 |
+| `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`                                                                                                                                                                                                                                      |
 
 `permissions([...names])` builds the decimal-string bitfield Discord expects, and
 `permissionNames(bitfield)` reads one back; `Permission` holds the bits themselves.
@@ -115,6 +115,26 @@ features on, and `modifyOnboarding` is a `PUT` that replaces the whole config.
 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`.
+
+### Linking members to the role
+
+`createDiscordOAuthClient({ clientId, clientSecret, redirectUri })` is "sign in with Discord": `authorizeUrl({ state })`
+builds the link a member opens, `exchangeCode(code)` trades what Discord sends back for a token, and `user(token)` and
+`connections(token)` read who they are and which accounts they have linked. `findVerifiedConnection(connections, "github")`
+picks the GitHub account Discord has confirmed they own (an unverified name proves nothing). `revoke(token)` discards the
+token once it has been read; nothing needs to keep it. `signOAuthState(secret)` and `verifyOAuthState(secret, state)` make
+and check a `state` that expires and cannot be forged, so a server with no storage can still refuse a forged callback.
+
+`guilds.membersWithRole(guildId, roleId)` lists who holds a role; like `guilds.members` it needs the privileged **Server
+Members Intent**, switched on in the developer portal. `guilds.member(guildId, userId)` reads one member and needs no intent.
+
+### Servers and checks
+
+`guilds.create` makes a server the bot owns (only a bot in fewer than ten servers may), `guilds.modify(id, { owner_id })`
+hands it over, `channels.createInvite` makes the link to join it, and `guilds.delete` removes it. On the webhook resource,
+`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.
+
 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

@@ -67,6 +67,8 @@ interface DiscordGuild {
 }
 interface ModifyGuildInput {
   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?: number;
   default_message_notifications?: number;
   explicit_content_filter?: number;
@@ -164,6 +166,16 @@ interface ModifyChannelInput {
   parent_id?: string | null;
   permission_overwrites?: DiscordPermissionOverwrite[];
 }
+/** A member of a server. Only what provisioning needs: who they are and which roles they hold. */
+interface DiscordGuildMember {
+  user?: {
+    id: string;
+    username?: string;
+  };
+  /** Ids of the roles the member holds. */
+  roles: string[];
+  nick?: string | null;
+}
 interface DiscordRole {
   id: string;
   name: string;
@@ -262,6 +274,50 @@ interface ModifyWebhookInput {
   /** 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. */
+interface CreateGuildInput {
+  name: string;
+  /** A data URI (`data:image/png;base64,...`). */
+  icon?: string;
+  verification_level?: number;
+  default_message_notifications?: number;
+  explicit_content_filter?: number;
+}
+/** Page options for `guilds.members`; Discord caps `limit` at 1000. */
+interface ListMembersInput {
+  limit?: number;
+  /** Return members after this user id. */
+  after?: string;
+}
+interface DiscordEmoji {
+  id: string | null;
+  name: string | null;
+  animated?: boolean;
+  available?: boolean;
+}
+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;
+  temporary?: boolean;
+  unique?: boolean;
+}
+interface DiscordInvite {
+  code: string;
+  channel_id?: string;
+  uses?: number;
+}
+/** A message listed back from a channel, with who wrote it. */
+interface DiscordChannelMessage extends DiscordMessage {
+  author?: {
+    id: string;
+    username?: string;
+    bot?: boolean;
+  };
+  webhook_id?: string;
+  pinned?: boolean;
+}
 //#endregion
 //#region ../../../../../src/bot/bot.d.ts
 /**
@@ -279,9 +335,15 @@ declare function createDiscordBotClient(opts: DiscordBotClientOptions): {
   users: {
     /** `GET /users/@me` — the bot's own user; a cheap token check. */
     me: () => Promise<DiscordUser>;
+    /** `GET /users/:id` — a user's name, for reports that would otherwise show a bare id. */
+    get: (userId: string) => Promise<DiscordUser>;
   };
   guilds: {
     get: (guildId: string) => Promise<DiscordGuild>;
+    /** `POST /guilds` — a new server the bot owns. Not idempotent: look one up by name before retrying. */
+    create: (body: CreateGuildInput) => Promise<DiscordGuild>;
+    /** `DELETE /guilds/:id` — only the owner may; a 404 counts as done. */
+    delete: (guildId: string) => Promise<void>;
     /** `PATCH /guilds/:id` — verification, notification defaults, content filter, system channels. */
     modify: (guildId: string, body: ModifyGuildInput) => Promise<DiscordGuild>;
     welcomeScreen: (guildId: string) => Promise<DiscordWelcomeScreen>;
@@ -298,12 +360,34 @@ declare function createDiscordBotClient(opts: DiscordBotClientOptions): {
     roles: (guildId: string) => Promise<DiscordRole[]>;
     createRole: (guildId: string, body: CreateRoleInput) => Promise<DiscordRole>;
     modifyRole: (guildId: string, roleId: string, body: ModifyRoleInput) => Promise<DiscordRole>;
+    /** `GET /guilds/:id/members/:id` — one member and the roles they hold. A 404 means either they are not in the server or the guild id is unknown; read the error body to tell them apart. */
+    member: (guildId: string, userId: string) => Promise<DiscordGuildMember>;
+    /**
+     * `GET /guilds/:id/members` — one page. Needs the privileged Server Members Intent, switched on in the
+     * developer portal; without it Discord answers 403.
+     */
+    members: (guildId: string, opts?: ListMembersInput) => Promise<DiscordGuildMember[]>;
+    /** Every member holding the role, read page by page; needs the same intent as `members`. */
+    membersWithRole: (guildId: string, roleId: string) => Promise<DiscordGuildMember[]>;
+    /** `GET /guilds/:id/emojis` — custom emoji, for welcome screen and onboarding ids. */
+    emojis: (guildId: string) => Promise<DiscordEmoji[]>;
+    /** `PUT /guilds/:id/members/:id/roles/:id` — gives the member the role; giving one they have is a no-op. */
+    addMemberRole: (guildId: string, userId: string, roleId: string) => Promise<void>;
+    /** `DELETE /guilds/:id/members/:id/roles/:id` — takes the role away; taking one they lack is a no-op. */
+    removeMemberRole: (guildId: string, userId: string, roleId: string) => Promise<void>;
   };
   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>;
+    /** `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. */
+    messages: (channelId: string, limit?: number) => Promise<DiscordChannelMessage[]>;
+    /** `PUT /channels/:id/pins/:id` — pins a message; one already pinned is a no-op. */
+    pin: (channelId: string, messageId: string) => Promise<void>;
+    deleteMessage: (channelId: string, messageId: string) => Promise<void>;
     createWebhook: (channelId: string, body: {
       name: string;
     }) => Promise<DiscordChannelWebhook>;
@@ -388,13 +472,121 @@ 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/oauth/oauth.type.d.ts
+interface DiscordOAuthClientOptions {
+  /** The application's client id (the same as its application id). Not a secret. */
+  clientId: string;
+  /** The application's client secret, from the developer portal (OAuth2 → Reset Secret). */
+  clientSecret: string;
+  /** One of the redirect URIs registered on the application; Discord refuses any other. */
+  redirectUri: string;
+  /** Override the API base for testing. Defaults to https://discord.com/api/v10. */
+  baseUrl?: string;
+  /** Override the authorize page for testing. Defaults to https://discord.com/oauth2/authorize. */
+  authorizeUrl?: string;
+  /** Override fetch for testing. Defaults to globalThis.fetch. */
+  fetch?: typeof fetch;
+  /** Per-request deadline in milliseconds. Defaults to 15000. */
+  timeoutMs?: number;
+}
+/** What a member's token may do: `identify` reads who they are, `connections` reads their linked accounts. */
+type DiscordOAuthScope = "identify" | "connections";
+interface DiscordOAuthToken {
+  access_token: string;
+  token_type: string;
+  /** Seconds until `access_token` stops working. */
+  expires_in: number;
+  refresh_token?: string;
+  /** The scopes granted, space separated. */
+  scope: string;
+}
+/** A linked account on a member's profile, as `GET /users/@me/connections` returns it. */
+interface DiscordConnection {
+  /** The id on the other service; for GitHub, the numeric user id. */
+  id: string;
+  /** The name on the other service; for GitHub, the login. */
+  name: string;
+  /** The service, lower case: `github`, `twitch`, … */
+  type: string;
+  /** Whether Discord confirmed the member owns the account. */
+  verified: boolean;
+  visibility?: number;
+}
+/** The member who signed in, as `GET /users/@me` returns it with their token. */
+interface DiscordOAuthUser {
+  id: string;
+  username: string;
+  global_name?: string | null;
+}
+//#endregion
+//#region ../../../../../src/oauth/oauth.d.ts
+/**
+ * Discord OAuth2 for "sign in with Discord": build the link a member follows, trade the code Discord sends
+ * back for a token, and read who they are and which accounts they have linked. Used to learn a member's
+ * Discord id together with their GitHub account, which Discord has verified.
+ *
+ * The token endpoints take a form body and the client's own credentials, which `createDiscordBotClient`'s
+ * JSON + bot-token client cannot send, so this has its own small transport.
+ */
+declare function createDiscordOAuthClient(opts: DiscordOAuthClientOptions): {
+  /**
+   * The page a member opens to approve the application. `state` must be unguessable and checked when
+   * Discord sends the member back (see {@link signOAuthState}). `prompt: "none"` skips the approval
+   * screen for a member who already approved.
+   */
+  authorizeUrl: (input: {
+    state: string;
+    scopes?: readonly DiscordOAuthScope[];
+    prompt?: "consent" | "none";
+  }) => string;
+  /** `POST /oauth2/token` — trades the one-use `code` from the redirect for a token. */
+  exchangeCode: (code: string) => Promise<DiscordOAuthToken>;
+  /** `POST /oauth2/token` — a fresh token from a `refresh_token`. */
+  refresh: (refreshToken: string) => Promise<DiscordOAuthToken>;
+  /** `POST /oauth2/token/revoke` — discards a token once it has been used; nothing needs to keep it. */
+  revoke: (token: string) => Promise<void>;
+  /** `GET /users/@me` as the member (needs `identify`). */
+  user: (accessToken: string) => Promise<DiscordOAuthUser>;
+  /** `GET /users/@me/connections` as the member (needs `connections`). */
+  connections: (accessToken: string) => Promise<DiscordConnection[]>;
+};
+type DiscordOAuthClient = ReturnType<typeof createDiscordOAuthClient>;
+/**
+ * The verified connection of one service, or `undefined`. Unverified ones are ignored: anyone can type a
+ * GitHub name into their profile, and only a verified link proves they own it. When a member has several
+ * of the service, the first verified one wins.
+ */
+declare function findVerifiedConnection(connections: readonly DiscordConnection[], type: string): DiscordConnection | undefined;
+//#endregion
+//#region ../../../../../src/oauth/state.d.ts
+/** How long a sign-in link stays valid by default, in seconds. */
+declare const DEFAULT_STATE_TTL_SECONDS = 600;
+/**
+ * An OAuth `state` that a stateless server can check without storing anything: a random nonce and an
+ * expiry, signed with a server-side secret. Tampering with either, or using a different secret, fails
+ * {@link verifyOAuthState}. It does not bind the link to one browser: set the nonce in a cookie as well
+ * when that matters.
+ */
+declare function signOAuthState(secret: string, opts?: {
+  now?: number;
+  ttlSeconds?: number;
+}): string;
+/** Whether `state` was signed with `secret` and has not expired. Never throws on malformed input. */
+declare function verifyOAuthState(secret: string, state: string, opts?: {
+  now?: number;
+}): boolean;
+//#endregion
 //#region ../../../../../src/index.d.ts
 declare function createDiscordClient(opts?: DiscordClientOptions): {
   webhooks: {
     get: (id: string, token: string) => Promise<DiscordWebhookInfo>;
     execute: (id: string, token: string, content: string) => Promise<void>;
+    executeAndWait: (id: string, token: string, content: string) => Promise<{
+      id: string;
+    }>;
+    deleteMessage: (id: string, token: string, messageId: string) => Promise<void>;
   };
 };
 type DiscordClient = ReturnType<typeof createDiscordClient>;
 //#endregion
-export { ChannelType, CreateChannelInput, CreateMessageInput, CreateRoleInput, DiscordApplication, DiscordBotClient, DiscordBotClientOptions, DiscordChannel, DiscordChannelWebhook, DiscordClient, type DiscordClientOptions, DiscordEmoji, DiscordGuild, DiscordInstallParams, DiscordMessage, DiscordOnboarding, DiscordOnboardingOption, DiscordOnboardingPrompt, DiscordPermissionOverwrite, DiscordRole, DiscordUser, type DiscordWebhookInfo, DiscordWelcomeChannel, DiscordWelcomeScreen, ModifyApplicationInput, ModifyChannelInput, ModifyGuildInput, ModifyRoleInput, ModifyWebhookInput, ModifyWelcomeScreenInput, Permission, PermissionName, createDiscordBotClient, createDiscordClient, parseWebhookUrl, permissionNames, permissions };
+export { ChannelType, CreateChannelInput, CreateGuildInput, CreateInviteInput, CreateMessageInput, CreateRoleInput, DEFAULT_STATE_TTL_SECONDS, DiscordApplication, DiscordBotClient, DiscordBotClientOptions, DiscordChannel, DiscordChannelMessage, DiscordChannelWebhook, DiscordClient, type DiscordClientOptions, DiscordConnection, DiscordEmoji, DiscordGuild, DiscordGuildMember, DiscordInstallParams, DiscordInvite, DiscordMessage, DiscordOAuthClient, DiscordOAuthClientOptions, DiscordOAuthScope, DiscordOAuthToken, DiscordOAuthUser, DiscordOnboarding, DiscordOnboardingOption, DiscordOnboardingPrompt, DiscordPermissionOverwrite, DiscordRole, DiscordUser, type DiscordWebhookInfo, DiscordWelcomeChannel, DiscordWelcomeScreen, ListMembersInput, ModifyApplicationInput, ModifyChannelInput, ModifyGuildInput, ModifyRoleInput, ModifyWebhookInput, ModifyWelcomeScreenInput, Permission, PermissionName, createDiscordBotClient, createDiscordClient, createDiscordOAuthClient, findVerifiedConnection, parseWebhookUrl, permissionNames, permissions, signOAuthState, verifyOAuthState };

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import { ProviderApiError, createRestClient } from "@theholocron/http-client";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 //#endregion
 //#region ../../../../../src/webhooks/webhooks.ts
 /**
@@ -32,6 +33,36 @@ function webhooks(base, f) {
 				throw new ProviderApiError(`Discord POST /webhooks failed: ${detail}`, 0, void 0);
 			}
 			if (!res.ok) throw new ProviderApiError(`Discord webhook POST failed (${res.status})`, res.status, void 0);
+		},
+		/** Posts and waits for Discord to answer with the message, so a check can read it back or delete it. */
+		executeAndWait: async (id, token, content) => {
+			let res;
+			try {
+				res = await f(`${base}/webhooks/${id}/${token}?wait=true`, {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify({
+						content,
+						allowed_mentions: { parse: [] }
+					})
+				});
+			} catch (err) {
+				const detail = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+				throw new ProviderApiError(`Discord POST /webhooks failed: ${detail}`, 0, void 0);
+			}
+			if (!res.ok) throw new ProviderApiError(`Discord webhook POST failed (${res.status})`, res.status, void 0);
+			return res.json();
+		},
+		/** Removes a message this webhook posted, e.g. a smoke-test line. A 404 counts as done. */
+		deleteMessage: async (id, token, messageId) => {
+			let res;
+			try {
+				res = await f(`${base}/webhooks/${id}/${token}/messages/${messageId}`, { method: "DELETE" });
+			} catch (err) {
+				const detail = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+				throw new ProviderApiError(`Discord DELETE /webhooks failed: ${detail}`, 0, void 0);
+			}
+			if (!res.ok && res.status !== 404) throw new ProviderApiError(`Discord webhook DELETE failed (${res.status})`, res.status, void 0);
 		}
 	};
 }
@@ -46,10 +77,12 @@ function parseWebhookUrl(url) {
 }
 //#endregion
 //#region ../../../../../src/bot/bot.ts
-const DEFAULT_TIMEOUT_MS = 15e3;
+const DEFAULT_TIMEOUT_MS$1 = 15e3;
 const DEFAULT_MAX_RETRIES = 3;
 /** A rate-limit wait longer than this fails fast instead of stalling the caller. */
 const MAX_RETRY_WAIT_MS = 1e4;
+/** A guard on `membersWithRole`, so a runaway cursor cannot loop forever. */
+const MAX_MEMBER_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)}`);
@@ -115,20 +148,40 @@ function createDiscordBotClient(opts) {
 		apiKeyHeader: "authorization",
 		vendor: "Discord",
 		fetch: guardedFetch(opts.fetch ?? globalThis.fetch, {
-			timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+			timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS$1,
 			maxRetries: opts.maxRetries ?? DEFAULT_MAX_RETRIES,
 			sleep: opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))
 		})
 	});
 	return {
-		users: { 
-		/** `GET /users/@me` — the bot's own user; a cheap token check. */
-me: () => rest.request("/users/@me") },
+		users: {
+			/** `GET /users/@me` — the bot's own user; a cheap token check. */
+			me: () => rest.request("/users/@me"),
+			/** `GET /users/:id` — a user's name, for reports that would otherwise show a bare id. */
+			get: (userId) => rest.request(`/users/${id(userId)}`)
+		},
 		guilds: {
 			get: (guildId) => rest.request(`/guilds/${id(guildId)}`),
+			/** `POST /guilds` — a new server the bot owns. Not idempotent: look one up by name before retrying. */
+			create: (body) => rest.request("/guilds", {
+				method: "POST",
+				body
+			}),
+			/** `DELETE /guilds/:id` — only the owner may; a 404 counts as done. */
+			delete: async (guildId) => {
+				try {
+					await rest.request(`/guilds/${id(guildId)}`, {
+						method: "DELETE",
+						expectNoContent: true
+					});
+				} catch (err) {
+					if (err instanceof ProviderApiError && err.status === 404) return;
+					throw err;
+				}
+			},
 			/** `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);
+				bodyIds(body.owner_id, body.system_channel_id, body.rules_channel_id, body.public_updates_channel_id);
 				return rest.request(`/guilds/${id(guildId)}`, {
 					method: "PATCH",
 					body
@@ -169,6 +222,46 @@ me: () => rest.request("/users/@me") },
 			modifyRole: (guildId, roleId, body) => rest.request(`/guilds/${id(guildId)}/roles/${id(roleId)}`, {
 				method: "PATCH",
 				body
+			}),
+			/** `GET /guilds/:id/members/:id` — one member and the roles they hold. A 404 means either they are not in the server or the guild id is unknown; read the error body to tell them apart. */
+			member: (guildId, userId) => rest.request(`/guilds/${id(guildId)}/members/${id(userId)}`),
+			/**
+			* `GET /guilds/:id/members` — one page. Needs the privileged Server Members Intent, switched on in the
+			* developer portal; without it Discord answers 403.
+			*/
+			members: (guildId, opts = {}) => {
+				const query = { limit: String(opts.limit ?? 1e3) };
+				if (opts.after !== void 0) query.after = id(opts.after);
+				return rest.request(`/guilds/${id(guildId)}/members`, { query });
+			},
+			/** Every member holding the role, read page by page; needs the same intent as `members`. */
+			membersWithRole: async (guildId, roleId) => {
+				const wanted = id(roleId);
+				const found = [];
+				let after;
+				for (let page = 0; page < MAX_MEMBER_PAGES; page++) {
+					const batch = await rest.request(`/guilds/${id(guildId)}/members`, { query: {
+						limit: "1000",
+						...after === void 0 ? {} : { after }
+					} });
+					for (const m of batch) if (m.roles.includes(wanted)) found.push(m);
+					const last = batch[batch.length - 1]?.user?.id;
+					if (batch.length < 1e3 || last === void 0) return found;
+					after = last;
+				}
+				throw new Error(`more than ${MAX_MEMBER_PAGES * 1e3} members; refusing to read them all`);
+			},
+			/** `GET /guilds/:id/emojis` — custom emoji, for welcome screen and onboarding ids. */
+			emojis: (guildId) => rest.request(`/guilds/${id(guildId)}/emojis`),
+			/** `PUT /guilds/:id/members/:id/roles/:id` — gives the member the role; giving one they have is a no-op. */
+			addMemberRole: (guildId, userId, roleId) => rest.request(`/guilds/${id(guildId)}/members/${id(userId)}/roles/${id(roleId)}`, {
+				method: "PUT",
+				expectNoContent: true
+			}),
+			/** `DELETE /guilds/:id/members/:id/roles/:id` — takes the role away; taking one they lack is a no-op. */
+			removeMemberRole: (guildId, userId, roleId) => rest.request(`/guilds/${id(guildId)}/members/${id(userId)}/roles/${id(roleId)}`, {
+				method: "DELETE",
+				expectNoContent: true
 			})
 		},
 		channels: {
@@ -188,6 +281,22 @@ me: () => rest.request("/users/@me") },
 					}
 				});
 			},
+			/** `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",
+				body
+			}),
+			/** `GET /channels/:id/messages` — the newest messages first, to read a post back. */
+			messages: (channelId, limit = 50) => rest.request(`/channels/${id(channelId)}/messages`, { query: { limit: String(limit) } }),
+			/** `PUT /channels/:id/pins/:id` — pins a message; one already pinned is a no-op. */
+			pin: (channelId, messageId) => rest.request(`/channels/${id(channelId)}/pins/${id(messageId)}`, {
+				method: "PUT",
+				expectNoContent: true
+			}),
+			deleteMessage: (channelId, messageId) => rest.request(`/channels/${id(channelId)}/messages/${id(messageId)}`, {
+				method: "DELETE",
+				expectNoContent: true
+			}),
 			createWebhook: async (channelId, body) => withUrl(await rest.request(`/channels/${id(channelId)}/webhooks`, {
 				method: "POST",
 				body
@@ -309,9 +418,135 @@ function permissionNames(bitfield) {
 	return Object.keys(Permission).filter((name) => (bits & Permission[name]) !== 0n);
 }
 //#endregion
+//#region ../../../../../src/oauth/oauth.ts
+const DEFAULT_AUTHORIZE_URL = "https://discord.com/oauth2/authorize";
+const DEFAULT_TIMEOUT_MS = 15e3;
+/**
+* Discord OAuth2 for "sign in with Discord": build the link a member follows, trade the code Discord sends
+* back for a token, and read who they are and which accounts they have linked. Used to learn a member's
+* Discord id together with their GitHub account, which Discord has verified.
+*
+* The token endpoints take a form body and the client's own credentials, which `createDiscordBotClient`'s
+* JSON + bot-token client cannot send, so this has its own small transport.
+*/
+function createDiscordOAuthClient(opts) {
+	let base = opts.baseUrl ?? "https://discord.com/api/v10";
+	while (base.endsWith("/")) base = base.slice(0, -1);
+	const f = opts.fetch ?? globalThis.fetch;
+	const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const basic = `Basic ${btoa(`${opts.clientId}:${opts.clientSecret}`)}`;
+	async function call(path, init) {
+		const tag = `Discord ${init.method ?? "GET"} ${path}`;
+		let res;
+		try {
+			res = await f(`${base}${path}`, {
+				...init,
+				signal: AbortSignal.timeout(timeoutMs)
+			});
+		} catch (err) {
+			const detail = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+			throw new ProviderApiError(`${tag} failed: ${detail}`, 0, void 0);
+		}
+		if (!res.ok) {
+			const body = await res.text().catch(() => "");
+			throw new ProviderApiError(`${tag} → ${res.status}`, res.status, body);
+		}
+		return await res.json();
+	}
+	function form(fields) {
+		return {
+			method: "POST",
+			headers: {
+				authorization: basic,
+				"content-type": "application/x-www-form-urlencoded",
+				accept: "application/json"
+			},
+			body: new URLSearchParams(fields).toString()
+		};
+	}
+	function bearer(accessToken) {
+		return { headers: {
+			authorization: `Bearer ${accessToken}`,
+			accept: "application/json"
+		} };
+	}
+	return {
+		/**
+		* The page a member opens to approve the application. `state` must be unguessable and checked when
+		* Discord sends the member back (see {@link signOAuthState}). `prompt: "none"` skips the approval
+		* screen for a member who already approved.
+		*/
+		authorizeUrl: (input) => {
+			const url = new URL(opts.authorizeUrl ?? DEFAULT_AUTHORIZE_URL);
+			url.searchParams.set("client_id", opts.clientId);
+			url.searchParams.set("response_type", "code");
+			url.searchParams.set("redirect_uri", opts.redirectUri);
+			url.searchParams.set("scope", (input.scopes ?? ["identify", "connections"]).join(" "));
+			url.searchParams.set("state", input.state);
+			if (input.prompt) url.searchParams.set("prompt", input.prompt);
+			return url.toString();
+		},
+		/** `POST /oauth2/token` — trades the one-use `code` from the redirect for a token. */
+		exchangeCode: (code) => call("/oauth2/token", form({
+			grant_type: "authorization_code",
+			code,
+			redirect_uri: opts.redirectUri
+		})),
+		/** `POST /oauth2/token` — a fresh token from a `refresh_token`. */
+		refresh: (refreshToken) => call("/oauth2/token", form({
+			grant_type: "refresh_token",
+			refresh_token: refreshToken
+		})),
+		/** `POST /oauth2/token/revoke` — discards a token once it has been used; nothing needs to keep it. */
+		revoke: async (token) => {
+			await call("/oauth2/token/revoke", form({ token }));
+		},
+		/** `GET /users/@me` as the member (needs `identify`). */
+		user: (accessToken) => call("/users/@me", bearer(accessToken)),
+		/** `GET /users/@me/connections` as the member (needs `connections`). */
+		connections: (accessToken) => call("/users/@me/connections", bearer(accessToken))
+	};
+}
+/**
+* The verified connection of one service, or `undefined`. Unverified ones are ignored: anyone can type a
+* GitHub name into their profile, and only a verified link proves they own it. When a member has several
+* of the service, the first verified one wins.
+*/
+function findVerifiedConnection(connections, type) {
+	return connections.find((c) => c.type === type && c.verified);
+}
+//#endregion
+//#region ../../../../../src/oauth/state.ts
+function mac(secret, message) {
+	return createHmac("sha256", secret).update(message).digest("hex");
+}
+/** How long a sign-in link stays valid by default, in seconds. */
+const DEFAULT_STATE_TTL_SECONDS = 600;
+/**
+* An OAuth `state` that a stateless server can check without storing anything: a random nonce and an
+* expiry, signed with a server-side secret. Tampering with either, or using a different secret, fails
+* {@link verifyOAuthState}. It does not bind the link to one browser: set the nonce in a cookie as well
+* when that matters.
+*/
+function signOAuthState(secret, opts = {}) {
+	const body = `${Math.floor((opts.now ?? Date.now()) / 1e3) + (opts.ttlSeconds ?? 600)}.${randomBytes(16).toString("hex")}`;
+	return `${body}.${mac(secret, body)}`;
+}
+/** Whether `state` was signed with `secret` and has not expired. Never throws on malformed input. */
+function verifyOAuthState(secret, state, opts = {}) {
+	const parts = state.split(".");
+	if (parts.length !== 3) return false;
+	const [expires, nonce, sig] = parts;
+	if (!/^\d+$/.test(expires) || !/^[0-9a-f]{32}$/.test(nonce)) return false;
+	const want = Buffer.from(mac(secret, `${expires}.${nonce}`));
+	const got = Buffer.from(sig);
+	if (got.length !== want.length || !timingSafeEqual(got, want)) return false;
+	return Number(expires) >= Math.floor((opts.now ?? Date.now()) / 1e3);
+}
+//#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, Permission, createDiscordBotClient, createDiscordClient, parseWebhookUrl, permissionNames, permissions };
+export { ChannelType, DEFAULT_STATE_TTL_SECONDS, Permission, createDiscordBotClient, createDiscordClient, createDiscordOAuthClient, findVerifiedConnection, parseWebhookUrl, permissionNames, permissions, signOAuthState, verifyOAuthState };

package/package.json

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