@theholocron/discord-client 1.48.0 → 1.49.0

package/README.md

@@ -101,7 +101,7 @@ the create response.
 
 | Resource             | Methods                                                                                                                                                                                                                                                                |
 | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `client.users`       | `me()` — `GET /users/@me`, a cheap token check; `get(id)` — a user's name                                                                                                                                                                                              |
+| `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`                                                                                                                                                             |

package/dist/index.d.mts

@@ -45,6 +45,21 @@ interface DiscordUser {
   username: string;
   bot?: boolean;
 }
+/** A server as `GET /users/@me/guilds` lists it: a summary, not the full guild. */
+interface DiscordUserGuild {
+  id: string;
+  name: string;
+  /** Whether the caller (here, the bot) owns the server. */
+  owner: boolean;
+  /** The caller's permission bitfield in the server, as a decimal string. */
+  permissions?: string;
+}
+/** Page options for `users.guilds`; Discord allows a `limit` of 1–200; values outside that are clamped. */
+interface ListUserGuildsInput {
+  limit?: number;
+  /** Return servers after this server id. */
+  after?: string;
+}
 /** Guild fields `guilds.modify` can change; the numeric enums are Discord's own. */
 interface DiscordGuild {
   id: string;
@@ -359,10 +374,15 @@ declare function createDiscordBotClient(opts: DiscordBotClientOptions): {
     me: () => Promise<DiscordUser>;
     /** `GET /users/:id` — a user's name, for reports that would otherwise show a bare id. */
     get: (userId: string) => Promise<DiscordUser>;
+    /**
+     * `GET /users/@me/guilds` — one page of the servers the bot is in, each with whether it owns it. This is
+     * how a retry finds a server `guilds.create` already made, since that call is not idempotent.
+     */
+    guilds: (opts?: ListUserGuildsInput) => Promise<DiscordUserGuild[]>;
   };
   guilds: {
     get: (guildId: string) => Promise<DiscordGuild>;
-    /** `POST /guilds` — a new server the bot owns. Not idempotent: look one up by name before retrying. */
+    /** `POST /guilds` — a new server the bot owns. Not idempotent: look one up by name (`users.guilds`) before retrying. */
     create: (body: CreateGuildInput) => Promise<DiscordGuild>;
     /** `DELETE /guilds/:id` — only the owner may; a 404 counts as done. */
     delete: (guildId: string) => Promise<void>;
@@ -611,4 +631,4 @@ declare function createDiscordClient(opts?: DiscordClientOptions): {
 };
 type DiscordClient = ReturnType<typeof createDiscordClient>;
 //#endregion
-export { ApplicationFlag, 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 };
+export { ApplicationFlag, 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, DiscordUserGuild, type DiscordWebhookInfo, DiscordWelcomeChannel, DiscordWelcomeScreen, ListMembersInput, ListUserGuildsInput, ModifyApplicationInput, ModifyChannelInput, ModifyGuildInput, ModifyRoleInput, ModifyWebhookInput, ModifyWelcomeScreenInput, Permission, PermissionName, createDiscordBotClient, createDiscordClient, createDiscordOAuthClient, findVerifiedConnection, parseWebhookUrl, permissionNames, permissions, signOAuthState, verifyOAuthState };

package/dist/index.mjs

@@ -158,11 +158,20 @@ function createDiscordBotClient(opts) {
 			/** `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)}`)
+			get: (userId) => rest.request(`/users/${id(userId)}`),
+			/**
+			* `GET /users/@me/guilds` — one page of the servers the bot is in, each with whether it owns it. This is
+			* how a retry finds a server `guilds.create` already made, since that call is not idempotent.
+			*/
+			guilds: (opts = {}) => {
+				const query = { limit: String(Math.min(Math.max(opts.limit ?? 200, 1), 200)) };
+				if (opts.after !== void 0) query.after = id(opts.after);
+				return rest.request("/users/@me/guilds", { query });
+			}
 		},
 		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. */
+			/** `POST /guilds` — a new server the bot owns. Not idempotent: look one up by name (`users.guilds`) before retrying. */
 			create: (body) => rest.request("/guilds", {
 				method: "POST",
 				body

package/package.json

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