Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

REST methods cleanup #1217

Merged
merged 15 commits into from Aug 17, 2022
Merged

REST methods cleanup #1217

Show file tree
Hide file tree
Changes from 14 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
e4d82f3
refactor(GuildRoleEdit)!: use struct params
FedorLap2006 Jul 25, 2022
eb02a61
feat(GuildRoleCreate): initial parameters
FedorLap2006 Jul 25, 2022
9de66a0
refactor(ChannelEdit)!: replace ChannelEditComplex
FedorLap2006 Jul 25, 2022
bc1a3a8
chore: deprecate ChannelEditComplex
FedorLap2006 Jul 25, 2022
54f1caf
feat(GuildEmbed)!: allow partial edits
FedorLap2006 Jul 25, 2022
f86fc86
refactor(GuildEmbedEdit)!: use params struct
FedorLap2006 Jul 25, 2022
d232ee7
refactor(GuildMemberEdit)!: replace GuildMemberEditComplex
FedorLap2006 Jul 29, 2022
42c8c83
chore: deprecate GuildMemberEditComplex
FedorLap2006 Jul 29, 2022
a0df6c3
refactor(GuildEmojiCreate)!: use struct params
FedorLap2006 Jul 30, 2022
de772a9
refactor(GuildEmojiEdit)!: use struct params
FedorLap2006 Jul 30, 2022
1dacbbb
refactor(GuildMemberAdd)!: use struct params
FedorLap2006 Aug 7, 2022
fa79cf4
refactor(GuildTemplateEdit)!: use struct params
FedorLap2006 Aug 12, 2022
6193350
refactor(GuildTemplateCreate)!: use struct params
FedorLap2006 Aug 12, 2022
cd25316
chore(rest)!: use pointers for Params structs
FedorLap2006 Aug 17, 2022
8fb23f2
chore: grammar and style fixes in comments
FedorLap2006 Aug 17, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
167 changes: 53 additions & 114 deletions restapi.go
View file
Open in desktop
Expand Up @@ -760,22 +760,10 @@ func (s *Session) GuildMember(guildID, userID string) (st *Member, err error) {
}

// GuildMemberAdd force joins a user to the guild.
// accessToken : Valid access_token for the user.
// guildID : The ID of a Guild.
// userID : The ID of a User.
// nick : Value to set users nickname to
// roles : A list of role ID's to set on the member.
// mute : If the user is muted.
// deaf : If the user is deafened.
func (s *Session) GuildMemberAdd(accessToken, guildID, userID, nick string, roles []string, mute, deaf bool) (err error) {

data := struct {
AccessToken string `json:"access_token"`
Nick string `json:"nick,omitempty"`
Roles []string `json:"roles,omitempty"`
Mute bool `json:"mute,omitempty"`
Deaf bool `json:"deaf,omitempty"`
}{accessToken, nick, roles, mute, deaf}
// data : Parameters of the user to add.
func (s *Session) GuildMemberAdd(guildID, userID string, data *GuildMemberAddParams) (err error) {

_, err = s.RequestWithBucketID("PUT", EndpointGuildMember(guildID, userID), data, EndpointGuildMember(guildID, ""))
if err != nil {
Expand Down Expand Up @@ -808,25 +796,11 @@ func (s *Session) GuildMemberDeleteWithReason(guildID, userID, reason string) (e
return
}

// GuildMemberEdit edits the roles of a member.
// guildID : The ID of a Guild.
// userID : The ID of a User.
// roles : A list of role ID's to set on the member.
func (s *Session) GuildMemberEdit(guildID, userID string, roles []string) (err error) {

data := struct {
Roles []string `json:"roles"`
}{roles}

_, err = s.RequestWithBucketID("PATCH", EndpointGuildMember(guildID, userID), data, EndpointGuildMember(guildID, ""))
return
}

// GuildMemberEditComplex edits the nickname and roles of a member.
// GuildMemberEdit edits and returns updated member.
// guildID : The ID of a Guild.
// userID : The ID of a User.
// data : A GuildMemberEditData struct with the new nickname and roles
func (s *Session) GuildMemberEditComplex(guildID, userID string, data GuildMemberParams) (st *Member, err error) {
// data : Updated GuildMember data.
func (s *Session) GuildMemberEdit(guildID, userID string, data *GuildMemberParams) (st *Member, err error) {
var body []byte
body, err = s.RequestWithBucketID("PATCH", EndpointGuildMember(guildID, userID), data, EndpointGuildMember(guildID, ""))
if err != nil {
Expand All @@ -837,6 +811,15 @@ func (s *Session) GuildMemberEditComplex(guildID, userID string, data GuildMembe
return
}

// GuildMemberEditComplex edits the nickname and roles of a member.
// NOTE: deprecated, use GuildMemberEdit instead.
// guildID : The ID of a Guild.
// userID : The ID of a User.
// data : A GuildMemberEditData struct with the new nickname and roles
func (s *Session) GuildMemberEditComplex(guildID, userID string, data *GuildMemberParams) (st *Member, err error) {
return s.GuildMemberEdit(guildID, userID, data)
}

// GuildMemberMove moves a guild member from one voice channel to another/none
// guildID : The ID of a Guild.
// userID : The ID of a User.
Expand Down Expand Up @@ -1031,11 +1014,11 @@ func (s *Session) GuildRoles(guildID string) (st []*Role, err error) {
return // TODO return pointer
}

// GuildRoleCreate returns a new Guild Role.
// guildID: The ID of a Guild.
func (s *Session) GuildRoleCreate(guildID string) (st *Role, err error) {

body, err := s.RequestWithBucketID("POST", EndpointGuildRoles(guildID), nil, EndpointGuildRoles(guildID))
// GuildRoleCreate creates a new Guild Role and returns it.
// guildID : The ID of a Guild.
// data : New role parameters.
FedorLap2006 marked this conversation as resolved.
Show resolved Hide resolved
func (s *Session) GuildRoleCreate(guildID string, data *RoleParams) (st *Role, err error) {
body, err := s.RequestWithBucketID("POST", EndpointGuildRoles(guildID), data, EndpointGuildRoles(guildID))
if err != nil {
return
}
Expand All @@ -1045,30 +1028,17 @@ func (s *Session) GuildRoleCreate(guildID string) (st *Role, err error) {
return
}

// GuildRoleEdit updates an existing Guild Role with new values
// GuildRoleEdit updates an existing Guild Role and updated Role data.
FedorLap2006 marked this conversation as resolved.
Show resolved Hide resolved
// guildID : The ID of a Guild.
// roleID : The ID of a Role.
// name : The name of the Role.
// color : The color of the role (decimal, not hex).
// hoist : Whether to display the role's users separately.
// perm : The permissions for the role.
// mention : Whether this role is mentionable
func (s *Session) GuildRoleEdit(guildID, roleID, name string, color int, hoist bool, perm int64, mention bool) (st *Role, err error) {
// data : Updated Role data.
func (s *Session) GuildRoleEdit(guildID, roleID string, data *RoleParams) (st *Role, err error) {

// Prevent sending a color int that is too big.
if color > 0xFFFFFF {
err = fmt.Errorf("color value cannot be larger than 0xFFFFFF")
return nil, err
if data.Color != nil && *data.Color > 0xFFFFFF {
return nil, fmt.Errorf("color value cannot be larger than 0xFFFFFF")
}

data := struct {
Name string `json:"name"` // The role's name (overwrites existing)
Color int `json:"color"` // The color the role should have (as a decimal, not hex)
Hoist bool `json:"hoist"` // Whether to display the role's users separately
Permissions int64 `json:"permissions,string"` // The overall permissions number of the role (overwrites existing)
Mentionable bool `json:"mentionable"` // Whether this role is mentionable
}{name, color, hoist, perm, mention}

body, err := s.RequestWithBucketID("PATCH", EndpointGuildRole(guildID, roleID), data, EndpointGuildRole(guildID, ""))
if err != nil {
return
Expand Down Expand Up @@ -1286,12 +1256,10 @@ func (s *Session) GuildEmbed(guildID string) (st *GuildEmbed, err error) {
return
}

// GuildEmbedEdit returns the embed for a Guild.
// GuildEmbedEdit edits the embed of a Guild.
// guildID : The ID of a Guild.
func (s *Session) GuildEmbedEdit(guildID string, enabled bool, channelID string) (err error) {

data := GuildEmbed{enabled, channelID}

// data : New embed data.
FedorLap2006 marked this conversation as resolved.
Show resolved Hide resolved
func (s *Session) GuildEmbedEdit(guildID string, data *GuildEmbed) (err error) {
_, err = s.RequestWithBucketID("PATCH", EndpointGuildEmbed(guildID), data, EndpointGuildEmbed(guildID))
return
}
Expand Down Expand Up @@ -1359,19 +1327,10 @@ func (s *Session) GuildEmoji(guildID, emojiID string) (emoji *Emoji, err error)
return
}

// GuildEmojiCreate creates a new emoji
// GuildEmojiCreate creates a new Emoji.
// guildID : The ID of a Guild.
// name : The Name of the Emoji.
// image : The base64 encoded emoji image, has to be smaller than 256KB.
// roles : The roles for which this emoji will be whitelisted, can be nil.
func (s *Session) GuildEmojiCreate(guildID, name, image string, roles []string) (emoji *Emoji, err error) {

data := struct {
Name string `json:"name"`
Image string `json:"image"`
Roles []string `json:"roles,omitempty"`
}{name, image, roles}

// data : New Emoji data.
func (s *Session) GuildEmojiCreate(guildID string, data *EmojiParams) (emoji *Emoji, err error) {
body, err := s.RequestWithBucketID("POST", EndpointGuildEmojis(guildID), data, EndpointGuildEmojis(guildID))
if err != nil {
return
Expand All @@ -1381,18 +1340,11 @@ func (s *Session) GuildEmojiCreate(guildID, name, image string, roles []string)
return
}

// GuildEmojiEdit modifies an emoji
// GuildEmojiEdit modifies and returns updated emoji.
FedorLap2006 marked this conversation as resolved.
Show resolved Hide resolved
// guildID : The ID of a Guild.
// emojiID : The ID of an Emoji.
// name : The Name of the Emoji.
// roles : The roles for which this emoji will be whitelisted, if nil or empty the roles will be reset.
func (s *Session) GuildEmojiEdit(guildID, emojiID, name string, roles []string) (emoji *Emoji, err error) {

data := struct {
Name string `json:"name"`
Roles []string `json:"roles"`
}{name, roles}

// data : Updated emoji data.
FedorLap2006 marked this conversation as resolved.
Show resolved Hide resolved
func (s *Session) GuildEmojiEdit(guildID, emojiID string, data *EmojiParams) (emoji *Emoji, err error) {
body, err := s.RequestWithBucketID("PATCH", EndpointGuildEmoji(guildID, emojiID), data, EndpointGuildEmojis(guildID))
if err != nil {
return
Expand Down Expand Up @@ -1458,16 +1410,9 @@ func (s *Session) GuildTemplates(guildID string) (st []*GuildTemplate, err error
}

// GuildTemplateCreate creates a template for the guild
// guildID: The ID of the guild
// name: The name of the template (1-100 characters)
// description: The description for the template (0-120 characters)
func (s *Session) GuildTemplateCreate(guildID, name, description string) (st *GuildTemplate) {

data := struct {
Name string `json:"name"`
Description string `json:"description"`
}{name, description}

// guildID : The ID of the guild
// data : Template metadata
func (s *Session) GuildTemplateCreate(guildID string, data *GuildTemplateParams) (st *GuildTemplate) {
body, err := s.RequestWithBucketID("POST", EndpointGuildTemplates(guildID), data, EndpointGuildTemplates(guildID))
if err != nil {
return
Expand All @@ -1487,16 +1432,10 @@ func (s *Session) GuildTemplateSync(guildID, templateCode string) (err error) {
}

// GuildTemplateEdit modifies the template's metadata
// guildID: The ID of the guild
// templateCode: The code of the template
// name: The name of the template (1-100 characters)
// description: The description for the template (0-120 characters)
func (s *Session) GuildTemplateEdit(guildID, templateCode, name, description string) (st *GuildTemplate, err error) {

data := struct {
Name string `json:"name,omitempty"`
Description string `json:"description,omitempty"`
}{name, description}
// guildID : The ID of the guild
// templateCode : The code of the template
// data : New template metadata
func (s *Session) GuildTemplateEdit(guildID, templateCode string, data *GuildTemplateParams) (st *GuildTemplate, err error) {

body, err := s.RequestWithBucketID("PATCH", EndpointGuildTemplateSync(guildID, templateCode), data, EndpointGuildTemplateSync(guildID, ""))
if err != nil {
Expand Down Expand Up @@ -1532,26 +1471,26 @@ func (s *Session) Channel(channelID string) (st *Channel, err error) {
return
}

// ChannelEdit edits the given channel
// channelID : The ID of a Channel
// name : The new name to assign the channel.
func (s *Session) ChannelEdit(channelID, name string) (*Channel, error) {
return s.ChannelEditComplex(channelID, &ChannelEdit{
Name: name,
})
}

// ChannelEditComplex edits an existing channel, replacing the parameters entirely with ChannelEdit struct
// channelID : The ID of a Channel
// data : The channel struct to send
func (s *Session) ChannelEditComplex(channelID string, data *ChannelEdit) (st *Channel, err error) {
// ChannelEdit edits the given channel and returns the updated Channel data.
// channelID : The ID of a Channel.
// data : New Channel data.
func (s *Session) ChannelEdit(channelID string, data *ChannelEdit) (st *Channel, err error) {
body, err := s.RequestWithBucketID("PATCH", EndpointChannel(channelID), data, EndpointChannel(channelID))
if err != nil {
return
}

err = unmarshal(body, &st)
return

}

// ChannelEditComplex edits an existing channel, replacing the parameters entirely with ChannelEdit struct
// NOTE: deprecated, use ChannelEdit instead
// channelID : The ID of a Channel
// data : The channel struct to send
func (s *Session) ChannelEditComplex(channelID string, data *ChannelEdit) (st *Channel, err error) {
return s.ChannelEdit(channelID, data)
}

// ChannelDelete deletes the given channel
Expand Down
52 changes: 50 additions & 2 deletions structs.go
View file
Open in desktop
Expand Up @@ -491,6 +491,17 @@ func (e *Emoji) APIName() string {
return e.ID
}

// EmojiParams represents parameters needed to create or update an Emoji.
type EmojiParams struct {
// Name of the emoji
Name string `json:"name,omitempty"`
// A base64 encoded emoji image, has to be smaller than 256KB.
// NOTE: can be only set on creation.
Image string `json:"image,omitempty"`
// Roles for which this emoji will be available.
Roles []string `json:"roles,omitempty"`
}

// StickerFormat is the file format of the Sticker.
type StickerFormat int

Expand Down Expand Up @@ -984,6 +995,14 @@ type GuildTemplate struct {
IsDirty bool `json:"is_dirty"`
}

// GuildTemplateParams stores the data needed to create or update a GuildTemplate.
type GuildTemplateParams struct {
// The name of the template (1-100 characters)
Name string `json:"name,omitempty"`
// The description of the template (0-120 characters)
Description string `json:"description,omitempty"`
}

// MessageNotifications is the notification level for a guild
// https://discord.com/developers/docs/resources/guild#guild-object-default-message-notification-level
type MessageNotifications int
Expand Down Expand Up @@ -1083,6 +1102,20 @@ func (r *Role) Mention() string {
return fmt.Sprintf("<@&%s>", r.ID)
}

// RoleParams represents the parameters needed to create or update a Role
type RoleParams struct {
// The role's name
Name string `json:"name,omitempty"`
// The color the role should have (as a decimal, not hex)
Color *int `json:"color,omitempty"`
// Whether to display the role's users separately
Hoist *bool `json:"hoist,omitempty"`
// The overall permissions number of the role
Permissions *int64 `json:"permissions,omitempty,string"`
// Whether this role is mentionable
Mentionable *bool `json:"mentionable,omitempty"`
}

// Roles are a collection of Role
type Roles []*Role

Expand Down Expand Up @@ -1393,8 +1426,8 @@ type AutoModerationAction struct {

// A GuildEmbed stores data for a guild embed.
type GuildEmbed struct {
Enabled bool `json:"enabled"`
ChannelID string `json:"channel_id"`
Enabled *bool `json:"enabled,omitempty"`
ChannelID string `json:"channel_id,omitempty"`
}

// A GuildAuditLog stores data for a guild audit log.
Expand Down Expand Up @@ -1701,6 +1734,21 @@ type GuildMemberParams struct {
Roles *[]string `json:"roles,omitempty"`
}

// GuildMemberAddParams stores data needed to add a user to a guild.
// NOTE: All fields are optional, except AccessToken.
type GuildMemberAddParams struct {
// Valid access_token for the user.
AccessToken string `json:"access_token"`
// Value to set users nickname to.
Nick string `json:"nick,omitempty"`
// A list of role ID's to set on the member.
Roles []string `json:"roles,omitempty"`
// Whether the user is muted.
Mute bool `json:"mute,omitempty"`
// Whether the user is deafened.
Deaf bool `json:"deaf,omitempty"`
}

// An APIErrorMessage is an api error message returned from discord
type APIErrorMessage struct {
Code int `json:"code"`
Expand Down