1
0
Fork 0
mirror of https://github.com/diamondburned/arikawa.git synced 2024-12-13 08:55:12 +00:00
arikawa/api/guild.go

537 lines
19 KiB
Go

package api
import (
"io"
"net/url"
"github.com/diamondburned/arikawa/v2/discord" // for clarity
"github.com/diamondburned/arikawa/v2/internal/intmath"
"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://discord.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 intmath.Min(fetch, limit).
fetch = uint(intmath.Min(MaxGuildFetchLimit, int(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 {
if limit > 0 {
// Only fetch as much as we need. Since limit gradually decreases,
// we only need to fetch intmath.Min(fetch, limit).
fetch = uint(intmath.Min(MaxGuildFetchLimit, int(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://discord.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",
)
}
// GuildWidgetSettings returns the guild widget object.
//
// Requires the MANAGE_GUILD permission.
func (c *Client) GuildWidgetSettings(
guildID discord.GuildID) (*discord.GuildWidgetSettings, error) {
var ge *discord.GuildWidgetSettings
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.GuildWidgetSettings, error) {
var w *discord.GuildWidgetSettings
return w, c.RequestJSON(
&w, "PATCH",
EndpointGuilds+guildID.String()+"/widget",
httputil.WithJSONBody(data),
)
}
// GuildWidget returns the widget for the guild.
func (c *Client) GuildWidget(guildID discord.GuildID) (*discord.GuildWidget, error) {
var w *discord.GuildWidget
return w, c.RequestJSON(
&w, "GET",
EndpointGuilds+guildID.String()+"/widget.json")
}
// GuildVanityInvite returns the vanity invite for guilds that have that
// feature enabled. 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) GuildVanityInvite(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 GuildWidgetImageStyle 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 GuildWidgetImageStyle = "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 GuildWidgetImageStyle = "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 GuildWidgetImageStyle = "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 GuildWidgetImageStyle = "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 GuildWidgetImageStyle = "banner4"
)
// GuildWidgetImageURL returns a link to the PNG image widget for the guild.
//
// Requires no permissions or authentication.
func (c *Client) GuildWidgetImageURL(guildID discord.GuildID, img GuildWidgetImageStyle) string {
return EndpointGuilds + guildID.String() + "/widget.png?style=" + string(img)
}
// GuildWidgetImage returns a PNG image widget for the guild. Requires no permissions
// or authentication.
func (c *Client) GuildWidgetImage(guildID discord.GuildID, img GuildWidgetImageStyle) (io.ReadCloser, error) {
r, err := c.Request("GET", c.GuildWidgetImageURL(guildID, img))
if err != nil {
return nil, err
}
return r.GetBody(), nil
}