import { cacheHandlers } from "../controllers/cache.ts"; import { identifyPayload } from "../module/client.ts"; import { RequestManager } from "../module/requestManager.ts"; import { requestAllMembers } from "../module/shardingManager.ts"; import { Guild, Member, structures, Template, } from "../structures/structures.ts"; import { AuditLogs, BannedUser, BanOptions, ChannelCreateOptions, ChannelCreatePayload, ChannelTypes, CreateEmojisOptions, CreateGuildFromTemplate, CreateGuildPayload, CreateGuildTemplate, CreateRoleOptions, CreateServerOptions, EditEmojisOptions, EditGuildTemplate, EditIntegrationOptions, Errors, FetchMembersOptions, GetAuditLogsOptions, GuildEditOptions, GuildTemplate, ImageFormats, ImageSize, Intents, MemberCreatePayload, PositionSwap, PruneOptions, PrunePayload, RoleData, UpdateGuildPayload, UserPayload, } from "../types/types.ts"; import { formatImageURL } from "../utils/cdn.ts"; import { Collection } from "../utils/collection.ts"; import { endpoints } from "../utils/constants.ts"; import { botHasPermission, calculateBits } from "../utils/permissions.ts"; import { urlToBase64 } from "../utils/utils.ts"; /** Create a new guild. Returns a guild object on success. Fires a Guild Create Gateway event. This endpoint can be used only by bots in less than 10 guilds. */ export async function createServer(options: CreateServerOptions) { const guild = await RequestManager.post( endpoints.GUILDS, options, ) as CreateGuildPayload; return structures.createGuild(guild, 0); } /** Delete a guild permanently. User must be owner. Returns 204 No Content on success. Fires a Guild Delete Gateway event. */ export function deleteServer(guildID: string) { return RequestManager.delete(endpoints.GUILD(guildID)); } /** Gets an array of all the channels ids that are the children of this category. */ export function categoryChildrenIDs(guildID: string, id: string) { return cacheHandlers.filter( "channels", (channel) => channel.parentID === id && channel.guildID === guildID, ); } /** The full URL of the icon from Discords CDN. Undefined when no icon is set. */ export function guildIconURL( guild: Guild, size: ImageSize = 128, format?: ImageFormats, ) { return guild.icon ? formatImageURL(endpoints.GUILD_ICON(guild.id, guild.icon), size, format) : undefined; } /** The full URL of the splash from Discords CDN. Undefined if no splash is set. */ export function guildSplashURL( guild: Guild, size: ImageSize = 128, format?: ImageFormats, ) { return guild.splash ? formatImageURL( endpoints.GUILD_SPLASH(guild.id, guild.splash), size, format, ) : undefined; } /** The full URL of the banner from Discords CDN. Undefined if no banner is set. */ export function guildBannerURL( guild: Guild, size: ImageSize = 128, format?: ImageFormats, ) { return guild.banner ? formatImageURL( endpoints.GUILD_BANNER(guild.id, guild.banner), size, format, ) : undefined; } /** Create a channel in your server. Bot needs MANAGE_CHANNEL permissions in the server. */ export async function createGuildChannel( guild: Guild, name: string, options?: ChannelCreateOptions, ) { const hasPerm = await botHasPermission( guild.id, ["MANAGE_CHANNELS"], ); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_CHANNELS); } const result = (await RequestManager.post(endpoints.GUILD_CHANNELS(guild.id), { ...options, name, permission_overwrites: options?.permissionOverwrites?.map((perm) => ({ ...perm, allow: calculateBits(perm.allow), deny: calculateBits(perm.deny), })), type: options?.type || ChannelTypes.GUILD_TEXT, })) as ChannelCreatePayload; const channel = await structures.createChannel(result); return channel; } /** Delete a channel in your server. Bot needs MANAGE_CHANNEL permissions in the server. */ export async function deleteChannel( guildID: string, channelID: string, reason?: string, ) { const hasPerm = await botHasPermission( guildID, ["MANAGE_CHANNELS"], ); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_CHANNELS); } return RequestManager.delete(endpoints.CHANNEL(channelID), { reason }); } /** Returns a list of guild channel objects. * * ⚠️ **If you need this, you are probably doing something wrong. This is not intended for use. Your channels will be cached in your guild.** */ export async function getChannels(guildID: string, addToCache = true) { const result = await RequestManager.get( endpoints.GUILD_CHANNELS(guildID), ) as ChannelCreatePayload[]; return Promise.all(result.map(async (res) => { const channel = await structures.createChannel(res, guildID); if (addToCache) { cacheHandlers.set("channels", channel.id, channel); } return channel; })); } /** Fetches a single channel object from the api. * * ⚠️ **If you need this, you are probably doing something wrong. This is not intended for use. Your channels will be cached in your guild.** */ export async function getChannel(channelID: string, addToCache = true) { const result = await RequestManager.get( endpoints.GUILD_CHANNEL(channelID), ) as ChannelCreatePayload; const channel = await structures.createChannel(result, result.guild_id); if (addToCache) cacheHandlers.set("channels", channel.id, channel); return channel; } /** Modify the positions of channels on the guild. Requires MANAGE_CHANNELS permisison. */ export function swapChannels( guildID: string, channelPositions: PositionSwap[], ) { if (channelPositions.length < 2) { throw "You must provide atleast two channels to be swapped."; } return RequestManager.patch( endpoints.GUILD_CHANNELS(guildID), channelPositions, ); } /** Returns a guild member object for the specified user. * * ⚠️ **ADVANCED USE ONLY: Your members will be cached in your guild most likely. Only use this when you are absolutely sure the member is not cached.** */ export async function getMember( guildID: string, id: string, options?: { force?: boolean }, ) { const guild = await cacheHandlers.get("guilds", guildID); if (!guild && !options?.force) return; const data = await RequestManager.get( endpoints.GUILD_MEMBER(guildID, id), ) as MemberCreatePayload; const member = await structures.createMember(data, guildID); return member; } /** Returns guild member objects for the specified user by their nickname/username. * * ⚠️ **ADVANCED USE ONLY: Your members will be cached in your guild most likely. Only use this when you are absolutely sure the member is not cached.** */ export async function getMembersByQuery( guildID: string, name: string, limit = 1, ) { const guild = await cacheHandlers.get("guilds", guildID); if (!guild) return; return new Promise((resolve) => { requestAllMembers(guild, resolve, { query: name, limit }); }) as Promise>; } /** Create an emoji in the server. Emojis and animated emojis have a maximum file size of 256kb. Attempting to upload an emoji larger than this limit will fail and return 400 Bad Request and an error message, but not a JSON status code. If a URL is provided to the image parameter, Discordeno will automatically convert it to a base64 string internally. */ export async function createEmoji( guildID: string, name: string, image: string, options: CreateEmojisOptions, ) { const hasPerm = await botHasPermission(guildID, ["MANAGE_EMOJIS"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_EMOJIS); } if (image && !image.startsWith("data:image/")) { image = await urlToBase64(image); } return RequestManager.post(endpoints.GUILD_EMOJIS(guildID), { ...options, name, image, }); } /** Modify the given emoji. Requires the MANAGE_EMOJIS permission. */ export async function editEmoji( guildID: string, id: string, options: EditEmojisOptions, ) { const hasPerm = await botHasPermission(guildID, ["MANAGE_EMOJIS"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_EMOJIS); } return RequestManager.patch(endpoints.GUILD_EMOJI(guildID, id), { name: options.name, roles: options.roles, }); } /** Delete the given emoji. Requires the MANAGE_EMOJIS permission. Returns 204 No Content on success. */ export async function deleteEmoji( guildID: string, id: string, reason?: string, ) { const hasPerm = await botHasPermission(guildID, ["MANAGE_EMOJIS"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_EMOJIS); } return RequestManager.delete( endpoints.GUILD_EMOJI(guildID, id), { reason }, ); } /** Creates a url to the emoji from the Discord CDN. */ export function emojiURL(id: string, animated = false) { return `https://cdn.discordapp.com/emojis/${id}.${animated ? "gif" : "png"}`; } /** Create a new role for the guild. Requires the MANAGE_ROLES permission. */ export async function createGuildRole( guildID: string, options: CreateRoleOptions, reason?: string, ) { const hasPerm = await botHasPermission(guildID, ["MANAGE_ROLES"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_ROLES); } const bits = calculateBits(options.permissions || []); const result = await RequestManager.post( endpoints.GUILD_ROLES(guildID), { ...options, permissions: calculateBits(options?.permissions || []), reason, }, ); const roleData = result as RoleData; const role = await structures.createRole(roleData); const guild = await cacheHandlers.get("guilds", guildID); guild?.roles.set(role.id, role); return role; } /** Edit a guild role. Requires the MANAGE_ROLES permission. */ export async function editRole( guildID: string, id: string, options: CreateRoleOptions, ) { const hasPerm = await botHasPermission(guildID, ["MANAGE_ROLES"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_ROLES); } return RequestManager.patch(endpoints.GUILD_ROLE(guildID, id), { ...options, permissions: options.permissions ? calculateBits(options.permissions) : undefined, }); } /** Delete a guild role. Requires the MANAGE_ROLES permission. */ export async function deleteRole(guildID: string, id: string) { const hasPerm = await botHasPermission(guildID, ["MANAGE_ROLES"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_ROLES); } return RequestManager.delete(endpoints.GUILD_ROLE(guildID, id)); } /** Returns a list of role objects for the guild. * * ⚠️ **If you need this, you are probably doing something wrong. This is not intended for use. Your roles will be cached in your guild.** */ export async function getRoles(guildID: string) { const hasPerm = await botHasPermission(guildID, ["MANAGE_ROLES"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_ROLES); } return RequestManager.get(endpoints.GUILD_ROLES(guildID)); } /** Modify the positions of a set of role objects for the guild. Requires the MANAGE_ROLES permission. */ export async function swapRoles(guildID: string, rolePositons: PositionSwap) { const hasPerm = await botHasPermission(guildID, ["MANAGE_ROLES"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_ROLES); } return RequestManager.patch(endpoints.GUILD_ROLES(guildID), rolePositons); } /** Check how many members would be removed from the server in a prune operation. Requires the KICK_MEMBERS permission */ export async function getPruneCount(guildID: string, options: PruneOptions) { if (options.days < 1) { throw new Error(Errors.PRUNE_MIN_DAYS); } const hasPerm = await botHasPermission(guildID, ["KICK_MEMBERS"]); if (!hasPerm) { throw new Error(Errors.MISSING_KICK_MEMBERS); } const result = await RequestManager.get( endpoints.GUILD_PRUNE(guildID), { ...options, include_roles: options.roles.join(",") }, ) as PrunePayload; return result.pruned; } /** Begin pruning all members in the given time period */ export async function pruneMembers(guildID: string, options: PruneOptions) { if (options.days < 1) { throw new Error(Errors.PRUNE_MIN_DAYS); } const hasPerm = await botHasPermission(guildID, ["KICK_MEMBERS"]); if (!hasPerm) { throw new Error(Errors.MISSING_KICK_MEMBERS); } RequestManager.post( endpoints.GUILD_PRUNE(guildID), { ...options, include_roles: options.roles.join(",") }, ); } /** * ⚠️ BEGINNER DEVS!! YOU SHOULD ALMOST NEVER NEED THIS AND YOU CAN GET FROM cache.members.get() * * ADVANCED: * Highly recommended to use this function to fetch members instead of getMember from REST. * REST: 50/s global(across all shards) rate limit with ALL requests this included * GW(this function): 120/m(PER shard) rate limit. Meaning if you have 8 shards your limit is now 960/m. */ export function fetchMembers(guild: Guild, options?: FetchMembersOptions) { // You can request 1 member without the intent if ( (!options?.limit || options.limit > 1) && !(identifyPayload.intents & Intents.GUILD_MEMBERS) ) { throw new Error(Errors.MISSING_INTENT_GUILD_MEMBERS); } if (options?.userIDs?.length) { options.limit = options.userIDs.length; } return new Promise((resolve) => { requestAllMembers(guild, resolve, options); }) as Promise>; } /** Returns the audit logs for the guild. Requires VIEW AUDIT LOGS permission */ export async function getAuditLogs( guildID: string, options: GetAuditLogsOptions, ) { const hasPerm = await botHasPermission(guildID, ["VIEW_AUDIT_LOG"]); if (!hasPerm) { throw new Error(Errors.MISSING_VIEW_AUDIT_LOG); } return RequestManager.get(endpoints.GUILD_AUDIT_LOGS(guildID), { ...options, action_type: options.action_type ? AuditLogs[options.action_type] : undefined, limit: options.limit && options.limit >= 1 && options.limit <= 100 ? options.limit : 50, }); } /** Returns the guild embed object. Requires the MANAGE_GUILD permission. */ export async function getEmbed(guildID: string) { const hasPerm = await botHasPermission(guildID, ["MANAGE_GUILD"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_GUILD); } return RequestManager.get(endpoints.GUILD_EMBED(guildID)); } /** Modify a guild embed object for the guild. Requires the MANAGE_GUILD permission. */ export async function editEmbed( guildID: string, enabled: boolean, channelID?: string | null, ) { const hasPerm = await botHasPermission(guildID, ["MANAGE_GUILD"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_GUILD); } return RequestManager.patch( endpoints.GUILD_EMBED(guildID), { enabled, channel_id: channelID }, ); } /** Returns the code and uses of the vanity url for this server if it is enabled. Requires the MANAGE_GUILD permission. */ export function getVanityURL(guildID: string) { return RequestManager.get(endpoints.GUILD_VANITY_URL(guildID)); } /** Returns a list of integrations for the guild. Requires the MANAGE_GUILD permission. */ export async function getIntegrations(guildID: string) { const hasPerm = await botHasPermission(guildID, ["MANAGE_GUILD"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_GUILD); } return RequestManager.get(endpoints.GUILD_INTEGRATIONS(guildID)); } /** Modify the behavior and settings of an integration object for the guild. Requires the MANAGE_GUILD permission. */ export async function editIntegration( guildID: string, id: string, options: EditIntegrationOptions, ) { const hasPerm = await botHasPermission(guildID, ["MANAGE_GUILD"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_GUILD); } return RequestManager.patch( endpoints.GUILD_INTEGRATION(guildID, id), options, ); } /** Delete the attached integration object for the guild with this id. Requires MANAGE_GUILD permission. */ export async function deleteIntegration(guildID: string, id: string) { const hasPerm = await botHasPermission(guildID, ["MANAGE_GUILD"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_GUILD); } return RequestManager.delete(endpoints.GUILD_INTEGRATION(guildID, id)); } /** Sync an integration. Requires the MANAGE_GUILD permission. */ export async function syncIntegration(guildID: string, id: string) { const hasPerm = await botHasPermission(guildID, ["MANAGE_GUILD"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_GUILD); } return RequestManager.post(endpoints.GUILD_INTEGRATION_SYNC(guildID, id)); } /** Returns a list of ban objects for the users banned from this guild. Requires the BAN_MEMBERS permission. */ export async function getBans(guildID: string) { const hasPerm = await botHasPermission(guildID, ["BAN_MEMBERS"]); if (!hasPerm) { throw new Error(Errors.MISSING_BAN_MEMBERS); } const results = await RequestManager.get( endpoints.GUILD_BANS(guildID), ) as BannedUser[]; return new Collection( results.map((res) => [res.user.id, res]), ); } /** Returns a ban object for the given user or a 404 not found if the ban cannot be found. Requires the BAN_MEMBERS permission. */ export async function getBan(guildID: string, memberID: string) { const hasPerm = await botHasPermission(guildID, ["BAN_MEMBERS"]); if (!hasPerm) { throw new Error(Errors.MISSING_BAN_MEMBERS); } return RequestManager.get( endpoints.GUILD_BAN(guildID, memberID), ) as Promise; } /** Ban a user from the guild and optionally delete previous messages sent by the user. Requires the BAN_MEMBERS permission. */ export async function ban(guildID: string, id: string, options: BanOptions) { const hasPerm = await botHasPermission(guildID, ["BAN_MEMBERS"]); if (!hasPerm) { throw new Error(Errors.MISSING_BAN_MEMBERS); } return RequestManager.put( endpoints.GUILD_BAN(guildID, id), { ...options, delete_message_days: options.days }, ); } /** Remove the ban for a user. Requires BAN_MEMBERS permission */ export async function unban(guildID: string, id: string) { const hasPerm = await botHasPermission(guildID, ["BAN_MEMBERS"]); if (!hasPerm) { throw new Error(Errors.MISSING_BAN_MEMBERS); } return RequestManager.delete(endpoints.GUILD_BAN(guildID, id)); } /** Modify a guilds settings. Requires the MANAGE_GUILD permission. */ export async function editGuild(guildID: string, options: GuildEditOptions) { const hasPerm = await botHasPermission(guildID, ["MANAGE_GUILD"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_GUILD); } if (options.icon && !options.icon.startsWith("data:image/")) { options.icon = await urlToBase64(options.icon); } if (options.banner && !options.banner.startsWith("data:image/")) { options.banner = await urlToBase64(options.banner); } if (options.splash && !options.splash.startsWith("data:image/")) { options.splash = await urlToBase64(options.splash); } return RequestManager.patch(endpoints.GUILD(guildID), options); } /** Get all the invites for this guild. Requires MANAGE_GUILD permission */ export async function getInvites(guildID: string) { const hasPerm = await botHasPermission(guildID, ["MANAGE_GUILD"]); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_GUILD); } return RequestManager.get(endpoints.GUILD_INVITES(guildID)); } /** Leave a guild */ export function leaveGuild(guildID: string) { return RequestManager.delete(endpoints.GUILD_LEAVE(guildID)); } /** Returns a list of voice region objects for the guild. Unlike the similar /voice route, this returns VIP servers when the guild is VIP-enabled. */ export function getVoiceRegions(guildID: string) { return RequestManager.get(endpoints.GUILD_REGIONS(guildID)); } /** Returns a list of guild webhooks objects. Requires the MANAGE_WEBHOOKs permission. */ export async function getWebhooks(guildID: string) { const hasPerm = await botHasPermission( guildID, ["MANAGE_WEBHOOKS"], ); if (!hasPerm) { throw new Error(Errors.MISSING_MANAGE_WEBHOOKS); } return RequestManager.get(endpoints.GUILD_WEBHOOKS(guildID)); } /** This function will return the raw user payload in the rare cases you need to fetch a user directly from the API. */ export function getUser(userID: string) { return RequestManager.get(endpoints.USER(userID)) as Promise; } /** * ⚠️ **If you need this, you are probably doing something wrong. Always use cache.guilds.get() * * Advanced Devs: * This function fetches a guild's data. This is not the same data as a GUILD_CREATE. * So it does not cache the guild, you must do it manually. * */ export function getGuild(guildID: string, counts = true) { return RequestManager.get( endpoints.GUILD(guildID), { with_counts: counts }, ) as Promise; } /** Returns the guild template if it exists */ export function getGuildTemplate( guildID: string, templateCode: string, ) { return RequestManager.get( `${endpoints.GUILD_TEMPLATES(guildID)}/${templateCode}`, ) as Promise