package api import ( "io" "net/url" "github.com/diamondburned/arikawa/v2/discord" // for clarity "github.com/diamondburned/arikawa/v2/utils/httputil" "github.com/diamondburned/arikawa/v2/utils/json/option" ) // maxGuildFetchLimit is the limit of max guilds per request, as imposed by // Discord. const maxGuildFetchLimit = 100 var EndpointGuilds = Endpoint + "guilds/" // https://discordapp.com/developers/docs/resources/guild#create-guild-json-params type CreateGuildData struct { // Name is the name of the guild (2-100 characters) Name string `json:"name"` // VoiceRegion is the voice region id. VoiceRegion string `json:"region,omitempty"` // Icon is the base64 128x128 image for the guild icon. Icon *Image `json:"image,omitempty"` // Verification is the verification level. Verification *discord.Verification `json:"verification_level,omitempty"` // Notification is the default message notification level. Notification *discord.Notification `json:"default_message_notifications,omitempty"` // ExplicitFilter is the explicit content filter level. ExplicitFilter *discord.ExplicitFilter `json:"explicit_content_filter,omitempty"` // Roles are the new guild roles. // // When using the roles parameter, the first member of the array is used to // change properties of the guild's @everyone role. If you are trying to // bootstrap a guild with additional roles, keep this in mind. // // When using the roles parameter, the required id field within each role // object is an integer placeholder, and will be replaced by the API upon // consumption. Its purpose is to allow you to overwrite a role's // permissions in a channel when also passing in channels with the channels // array. Roles []discord.Role `json:"roles,omitempty"` // Channels are the new guild's channels. // Assigning a channel to a channel category is not supported by this // endpoint, i.e. a channel can't have the parent_id field. // // When using the channels parameter, the position field is ignored, // and none of the default channels are created. // // When using the channels parameter, the id field within each channel // object may be set to an integer placeholder, and will be replaced by the // API upon consumption. Its purpose is to allow you to create // GUILD_CATEGORY channels by setting the parent_id field on any children // to the category's id field. Category channels must be listed before any // children. Channels []discord.Channel `json:"channels,omitempty"` // AFKChannelID is the id for the afk channel. AFKChannelID discord.ChannelID `json:"afk_channel_id,omitempty"` // AFKTimeout is the afk timeout in seconds. AFKTimeout option.Seconds `json:"afk_timeout,omitempty"` // SystemChannelID is the id of the channel where guild notices such as // welcome messages and boost events are posted. SystemChannelID discord.ChannelID `json:"system_channel_id,omitempty"` } // CreateGuild creates 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. func (c *Client) CreateGuild(data CreateGuildData) (*discord.Guild, error) { var g *discord.Guild return g, c.RequestJSON(&g, "POST", Endpoint+"guilds", httputil.WithJSONBody(data)) } // Guild returns the guild object for the given id. // ApproximateMembers and ApproximatePresences will not be set. func (c *Client) Guild(id discord.GuildID) (*discord.Guild, error) { var g *discord.Guild return g, c.RequestJSON(&g, "GET", EndpointGuilds+id.String()) } // GuildPreview returns the guild preview object for the given id, even if the // user is not in the guild. // // This endpoint is only for public guilds. func (c *Client) GuildPreview(id discord.GuildID) (*discord.GuildPreview, error) { var g *discord.GuildPreview return g, c.RequestJSON(&g, "GET", EndpointGuilds+id.String()+"/preview") } // GuildWithCount returns the guild object for the given id. // This will also set the ApproximateMembers and ApproximatePresences fields // of the guild struct. func (c *Client) GuildWithCount(id discord.GuildID) (*discord.Guild, error) { var g *discord.Guild return g, c.RequestJSON( &g, "GET", EndpointGuilds+id.String(), httputil.WithSchema(c, url.Values{ "with_counts": {"true"}, }), ) } // Guilds returns a list of partial guild objects the current user is a member // of. This method automatically paginates until it reaches the passed limit, // or, if the limit is set to 0, has fetched all guilds the user has joined. // // As the underlying endpoint has a maximum of 100 guilds per request, at // maximum a total of limit/100 rounded up requests will be made, although they // may be less, if no more guilds are available. // // When fetching the guilds, those with the smallest ID will be fetched first. // // Also note that 100 is the maximum number of guilds a non-bot user can join. // Therefore, pagination is not needed for integrations that need to get a list // of the users' guilds. // // Requires the guilds OAuth2 scope. func (c *Client) Guilds(limit uint) ([]discord.Guild, error) { return c.GuildsAfter(0, limit) } // GuildsBefore returns a list of partial guild objects the current user is a // member of. This method automatically paginates until it reaches the // passed limit, or, if the limit is set to 0, has fetched all guilds with an // id smaller than before. // // As the underlying endpoint has a maximum of 100 guilds per request, at // maximum a total of limit/100 rounded up requests will be made, although they // may be less, if no more guilds are available. // // Requires the guilds OAuth2 scope. func (c *Client) GuildsBefore(before discord.GuildID, limit uint) ([]discord.Guild, error) { guilds := make([]discord.Guild, 0, limit) fetch := uint(maxGuildFetchLimit) unlimited := limit == 0 for limit > 0 || unlimited { if limit > 0 { // Only fetch as much as we need. Since limit gradually decreases, // we only need to fetch min(fetch, limit). if fetch > limit { fetch = limit } limit -= fetch } g, err := c.guildsRange(before, 0, fetch) if err != nil { return guilds, err } guilds = append(g, guilds...) if len(g) < maxGuildFetchLimit { break } before = g[0].ID } if len(guilds) == 0 { return nil, nil } return guilds, nil } // GuildsAfter returns a list of partial guild objects the current user is a // member of. This method automatically paginates until it reaches the // passed limit, or, if the limit is set to 0, has fetched all guilds with an // id higher than after. // // As the underlying endpoint has a maximum of 100 guilds per request, at // maximum a total of limit/100 rounded up requests will be made, although they // may be less, if no more guilds are available. // // Requires the guilds OAuth2 scope. func (c *Client) GuildsAfter(after discord.GuildID, limit uint) ([]discord.Guild, error) { guilds := make([]discord.Guild, 0, limit) fetch := uint(maxGuildFetchLimit) unlimited := limit == 0 for limit > 0 || unlimited { // Only fetch as much as we need. Since limit gradually decreases, // we only need to fetch min(fetch, limit). if limit > 0 { if fetch > limit { fetch = limit } limit -= fetch } g, err := c.guildsRange(0, after, fetch) if err != nil { return guilds, err } guilds = append(guilds, g...) if len(g) < maxGuildFetchLimit { break } after = g[len(g)-1].ID } if len(guilds) == 0 { return nil, nil } return guilds, nil } func (c *Client) guildsRange( before, after discord.GuildID, limit uint) ([]discord.Guild, error) { var param struct { Before discord.GuildID `schema:"before,omitempty"` After discord.GuildID `schema:"after,omitempty"` Limit uint `schema:"limit"` } param.Before = before param.After = after param.Limit = limit var gs []discord.Guild return gs, c.RequestJSON( &gs, "GET", EndpointMe+"/guilds", httputil.WithSchema(c, param), ) } // LeaveGuild leaves a guild. func (c *Client) LeaveGuild(id discord.GuildID) error { return c.FastRequest("DELETE", EndpointMe+"/guilds/"+id.String()) } // https://discordapp.com/developers/docs/resources/guild#modify-guild-json-params type ModifyGuildData struct { // Name is the guild's name. Name string `json:"name,omitempty"` // Region is the guild's voice region id. Region option.NullableString `json:"region,omitempty"` // Verification is the verification level. // // This field is nullable. Verification *discord.Verification `json:"verification_level,omitempty"` // Notification is the default message notification level. // // This field is nullable. Notification *discord.Notification `json:"default_message_notifications,omitempty"` // ExplicitFilter is the explicit content filter level. // // This field is nullable. ExplicitFilter *discord.ExplicitFilter `json:"explicit_content_filter,omitempty"` // AFKChannelID is the id for the afk channel. // // This field is nullable. AFKChannelID discord.ChannelID `json:"afk_channel_id,string,omitempty"` // AFKTimeout is the afk timeout in seconds. AFKTimeout option.Seconds `json:"afk_timeout,omitempty"` // Icon is the base64 1024x1024 png/jpeg/gif image for the guild icon // (can be animated gif when the server has the ANIMATED_ICON feature). Icon *Image `json:"icon,omitempty"` // Splash is the base64 16:9 png/jpeg image for the guild splash // (when the server has the INVITE_SPLASH feature). Splash *Image `json:"splash,omitempty"` // Banner is the base64 16:9 png/jpeg image for the guild banner (when the // server has BANNER feature). Banner *Image `json:"banner,omitempty"` // OwnerID is the user id to transfer guild ownership to (must be owner). OwnerID discord.UserID `json:"owner_id,omitempty"` // SystemChannelID is the id of the channel where guild notices such as // welcome messages and boost events are posted. // // This field is nullable. SystemChannelID discord.ChannelID `json:"system_channel_id,omitempty"` // RulesChannelID is the id of the channel where "PUBLIC" guilds display // rules and/or guidelines. // // This field is nullable. RulesChannelID discord.ChannelID `json:"rules_channel_id,omitempty"` // PublicUpdatesChannelID is the id of the channel where admins and // moderators of "PUBLIC" guilds receive notices from Discord. // // This field is nullable. PublicUpdatesChannelID discord.ChannelID `json:"public_updates_channel_id,omitempty"` // PreferredLocale is the preferred locale of a "PUBLIC" guild used in // server discovery and notices from Discord. // // This defaults to "en-US". PreferredLocale option.NullableString `json:"preferred_locale,omitempty"` } // ModifyGuild modifies a guild's settings. Requires the MANAGE_GUILD permission. // Fires a Guild Update Gateway event. func (c *Client) ModifyGuild(id discord.GuildID, data ModifyGuildData) (*discord.Guild, error) { var g *discord.Guild return g, c.RequestJSON( &g, "PATCH", EndpointGuilds+id.String(), httputil.WithJSONBody(data), ) } // DeleteGuild deletes a guild permanently. The User must be owner. // // Fires a Guild Delete Gateway event. func (c *Client) DeleteGuild(id discord.GuildID) error { return c.FastRequest("DELETE", EndpointGuilds+id.String()) } // GuildVoiceRegions is the same as /voice, but returns VIP ones as well if // available. func (c *Client) VoiceRegionsGuild(guildID discord.GuildID) ([]discord.VoiceRegion, error) { var vrs []discord.VoiceRegion return vrs, c.RequestJSON(&vrs, "GET", EndpointGuilds+guildID.String()+"/regions") } // https://discord.com/developers/docs/resources/audit-log#get-guild-audit-log-query-string-parameters type AuditLogData struct { // UserID filters the log for actions made by a user. UserID discord.UserID `schema:"user_id,omitempty"` // ActionType is the type of audit log event. ActionType discord.AuditLogEvent `schema:"action_type,omitempty"` // Before filters the log before a certain entry ID. Before discord.AuditLogEntryID `schema:"before,omitempty"` // Limit limits how many entries are returned (default 50, minimum 1, // maximum 100). Limit uint `schema:"limit"` } // AuditLog returns an audit log object for the guild. // // Requires the VIEW_AUDIT_LOG permission. func (c *Client) AuditLog(guildID discord.GuildID, data AuditLogData) (*discord.AuditLog, error) { switch { case data.Limit == 0: data.Limit = 50 case data.Limit > 100: data.Limit = 100 } var audit *discord.AuditLog return audit, c.RequestJSON( &audit, "GET", EndpointGuilds+guildID.String()+"/audit-logs", httputil.WithSchema(c, data), ) } // Integrations returns a list of integration objects for the guild. // // Requires the MANAGE_GUILD permission. func (c *Client) Integrations(guildID discord.GuildID) ([]discord.Integration, error) { var ints []discord.Integration return ints, c.RequestJSON(&ints, "GET", EndpointGuilds+guildID.String()+"/integrations") } // AttachIntegration attaches an integration object from the current user to // the guild. // // Requires the MANAGE_GUILD permission. // Fires a Guild Integrations Update Gateway event. func (c *Client) AttachIntegration( guildID discord.GuildID, integrationID discord.IntegrationID, integrationType discord.Service) error { var param struct { Type discord.Service `json:"type"` ID discord.IntegrationID `json:"id"` } param.Type = integrationType param.ID = integrationID return c.FastRequest( "POST", EndpointGuilds+guildID.String()+"/integrations", httputil.WithJSONBody(param), ) } // https://discord.com/developers/docs/resources/guild#modify-guild-integration-json-params type ModifyIntegrationData struct { // ExpireBehavior is the behavior when an integration subscription lapses // (see the integration expire behaviors documentation). ExpireBehavior *discord.ExpireBehavior `json:"expire_behavior,omitempty"` // ExpireGracePeriod is the period (in days) where the integration will // ignore lapsed subscriptions. ExpireGracePeriod option.NullableInt `json:"expire_grace_period,omitempty"` // EnableEmoticons specifies whether emoticons should be synced for this // integration (twitch only currently). EnableEmoticons option.NullableBool `json:"enable_emoticons,omitempty"` } // ModifyIntegration modifies the behavior and settings of an integration // object for the guild. // // Requires the MANAGE_GUILD permission. // Fires a Guild Integrations Update Gateway event. func (c *Client) ModifyIntegration( guildID discord.GuildID, integrationID discord.IntegrationID, data ModifyIntegrationData) error { return c.FastRequest( "PATCH", EndpointGuilds+guildID.String()+"/integrations/"+integrationID.String(), httputil.WithJSONBody(data), ) } // Sync an integration. Requires the MANAGE_GUILD permission. func (c *Client) SyncIntegration(guildID discord.GuildID, integrationID discord.IntegrationID) error { return c.FastRequest( "POST", EndpointGuilds+guildID.String()+"/integrations/"+integrationID.String()+"/sync", ) } // GuildWidget returns the guild widget object. // // Requires the MANAGE_GUILD permission. func (c *Client) GuildWidget(guildID discord.GuildID) (*discord.GuildWidget, error) { var ge *discord.GuildWidget return ge, c.RequestJSON(&ge, "GET", EndpointGuilds+guildID.String()+"/widget") } // ModifyGuildWidgetData is the structure to modify a guild widget object for // the guild. All attributes may be passed in with JSON and modified. // // https://discord.com/developers/docs/resources/guild#guild-widget-object type ModifyGuildWidgetData struct { // Enabled specifies whether the widget is enabled. Enabled option.Bool `json:"enabled,omitempty"` // ChannelID is the widget channel ID. ChannelID discord.ChannelID `json:"channel_id,omitempty"` } // ModifyGuildWidget modifies a guild widget object for the guild. // // Requires the MANAGE_GUILD permission. func (c *Client) ModifyGuildWidget( guildID discord.GuildID, data ModifyGuildWidgetData) (*discord.GuildWidget, error) { var w *discord.GuildWidget return w, c.RequestJSON( &w, "PATCH", EndpointGuilds+guildID.String()+"/widget", httputil.WithJSONBody(data), ) } // GuildVanityURL returns *Invite for guilds that have that feature enabled, // but only Code and Uses are filled. Code will be "" if a vanity url for the // guild is not set. // // Requires MANAGE_GUILD. func (c *Client) GuildVanityURL(guildID discord.GuildID) (*discord.Invite, error) { var inv *discord.Invite return inv, c.RequestJSON(&inv, "GET", EndpointGuilds+guildID.String()+"/vanity-url") } // https://discord.com/developers/docs/resources/guild#get-guild-widget-image-widget-style-options type GuildImageStyle string const ( // GuildShield is a shield style widget with Discord icon and guild members // online count. // // Example: https://discordapp.com/api/guilds/81384788765712384/widget.png?style=shield GuildShield GuildImageStyle = "shield" // GuildBanner1 is a large image with guild icon, name and online count. // "POWERED BY DISCORD" as the footer of the widget. // // Example: https://discordapp.com/api/guilds/81384788765712384/widget.png?style=banner1 GuildBanner1 GuildImageStyle = "banner1" // GuildBanner2 is a smaller widget style with guild icon, name and online // count. Split on the right with Discord logo. // // Example: https://discordapp.com/api/guilds/81384788765712384/widget.png?style=banner2 GuildBanner2 GuildImageStyle = "banner2" // GuildBanner3 is a large image with guild icon, name and online count. In // the footer, Discord logo on the left and "Chat Now" on the right. // // Example: https://discordapp.com/api/guilds/81384788765712384/widget.png?style=banner3 GuildBanner3 GuildImageStyle = "banner3" // GuildBanner4 is a large Discord logo at the top of the widget. // Guild icon, name and online count in the middle portion of the widget // and a "JOIN MY SERVER" button at the bottom. // // Example: https://discordapp.com/api/guilds/81384788765712384/widget.png?style=banner4 GuildBanner4 GuildImageStyle = "banner4" ) // GuildImageURL returns a link to the PNG image widget for the guild. // // Requires no permissions or authentication. func (c *Client) GuildImageURL(guildID discord.GuildID, img GuildImageStyle) string { return EndpointGuilds + guildID.String() + "/widget.png?style=" + string(img) } // GuildImage returns a PNG image widget for the guild. Requires no permissions // or authentication. func (c *Client) GuildImage(guildID discord.GuildID, img GuildImageStyle) (io.ReadCloser, error) { r, err := c.Request("GET", c.GuildImageURL(guildID, img)) if err != nil { return nil, err } return r.GetBody(), nil }