Readme (#20)

* Feature : Gateway Connection

* initial pass on all structs and codes required for gateway connection

Signed-off-by: Keith Russo <keith.russo@veteransoftware.us>

* Update README.md

Signed-off-by: Keith Russo <keith.russo@veteransoftware.us>

---------

Signed-off-by: Keith Russo <keith.russo@veteransoftware.us>

README.md

@@ -34,3 +34,11 @@ it. The Discord REST API changes frequently, so updating can be daunting at time
 ## Pull Requests
 
 If you wish to contribute to this wrapper, feel free to submit Pull Requests
+
+## Stargazers
+
+[![Stargazers repo roster for @veteran-software/discord-api-wrapper](https://reporoster.com/stars/veteran-software/discord-api-wrapper)](https://github.com/veteran-software/discord-api-wrapper/stargazers)
+
+## Forkers
+
+[![Forkers repo roster for @veteran-software/discord-api-wrapper](https://reporoster.com/forks/veteran-software/discord-api-wrapper)](https://github.com/veteran-software/discord-api-wrapper/network/members)

api/guild.go

@@ -61,20 +61,6 @@ type Guild struct {
 	Stickers                    []*Sticker                      `json:"stickers,omitempty"`                   // custom guild stickers
 	PremiumProgressBarEnabled   bool                            `json:"premium_progress_bar_enabled"`         // whether the guild has the boost progress bar enabled
 
-	// TODO: These fields are only sent within the GUILD_CREATE event; move to Gateway.go
-
-	JoinedAt             time.Time              `json:"joined_at,omitempty"`              // when this guild was joined at
-	Large                bool                   `json:"large,omitempty"`                  // true if this is considered a large guild
-	Unavailable          bool                   `json:"unavailable,omitempty"`            // true if this guild is unavailable due to an outage
-	MemberCount          int64                  `json:"member_count,omitempty"`           // total number of members in this guild
-	VoiceStates          []*VoiceState          `json:"voice_states,omitempty"`           // states of members currently in voice channels; lacks the guild_id key
-	Members              []*GuildMember         `json:"members,omitempty"`                // users in the guild
-	Channels             []*Channel             `json:"channels,omitempty"`               // channels in the guild
-	Threads              []*Channel             `json:"threads,omitempty"`                // all active threads in the guild that current user has permission to view
-	Presences            []*PresenceUpdateEvent `json:"presences,omitempty"`              // presences of the members in the guild, will only include non-offline members if the size is greater than large threshold
-	StageInstances       []*StageInstance       `json:"stage_instances,omitempty"`        // Stage instances in the guild
-	GuildScheduledEvents []*GuildScheduledEvent `json:"guild_scheduled_events,omitempty"` // the scheduled events in the guild
-
 	// These fields are only sent when using the GET CurrentUserGuilds endpoint and are relative to the requested user
 
 	Owner       bool   `json:"owner,omitempty"`       // true if the user is the owner of the guild

errors/messages.go

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2023. Veteran Software
+ *
+ * Discord API Wrapper - A custom wrapper for the Discord REST API developed for a proprietary project.
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
+ * License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later
+ * version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program.
+ * If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package errors
+
+type Errors struct {
+	Code    string `json:"code"`
+	Message string `json:"message"`
+}
+
+type ArrayError struct {
+	Code   int `json:"code"`
+	Errors struct {
+		Activities map[string]struct {
+			Platform struct {
+				Errors []Errors `json:"_errors"`
+			} `json:"platform"`
+			Type struct {
+				Errors []Errors `json:"_errors"`
+			} `json:"type"`
+		} `json:"activities"`
+	} `json:"errors"`
+	Message string `json:"message"`
+}
+
+type ObjectError struct {
+	Code   int `json:"code"`
+	Errors struct {
+		AccessToken struct {
+			Errors []Errors `json:"_errors"`
+		} `json:"access_token"`
+	} `json:"errors"`
+	Message string `json:"message"`
+}
+
+type RequestError struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+	Errors  struct {
+		Errors []Errors `json:"_errors"`
+	} `json:"errors"`
+}

gateway/close_codes.go

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2023. Veteran Software
+ *
+ * Discord API Wrapper - A custom wrapper for the Discord REST API developed for a proprietary project.
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
+ * License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later
+ * version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program.
+ * If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package gateway
+
+// Gateway Close Event Codes
+//
+// In order to prevent broken reconnect loops, you should consider some close codes as a signal to stop reconnecting.
+// This can be because your token expired, or your identification is invalid.
+// This table explains what the application defined close codes for the gateway are, and which close codes you should not attempt to reconnect.
+
+//goland:noinspection GoUnusedExportedFunction
+func GetCloseCode(c int) (code int, reconnect bool, description string) {
+	switch c {
+	case 4000:
+		return 4000, true, "Unknown Error"
+	case 4001:
+		return 4001, true, "Unknown opcode"
+	case 4002:
+		return 4002, true, "Decode Error"
+	case 4003:
+		return 4003, true, "Not Authenticated"
+	case 4004:
+		return 4004, false, "Authentication Failed"
+	case 4005:
+		return 4005, true, "Already Authenticated"
+	case 4007:
+		return 4007, true, "Invalid Sequence Number"
+	case 4008:
+		return 4008, true, "Rate Limited"
+	case 4009:
+		return 4009, true, "Session Timed Out"
+	case 4010:
+		return 4010, false, "Invalid Shard"
+	case 4011:
+		return 4011, false, "Sharding Required"
+	case 4012:
+		return 4012, false, "Invalid API Version"
+	case 4013:
+		return 4013, false, "Invalid Intent(s)"
+	case 4014:
+		return 4014, false, "Disallowed Intent(s)"
+	default:
+		return 0, false, "Unknown Close Code"
+	}
+}

gateway/events/receive/application_commands/events.go

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2023. Veteran Software
+ *
+ * Discord API Wrapper - A custom wrapper for the Discord REST API developed for a proprietary project.
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
+ * License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later
+ * version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program.
+ * If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package application_commands
+
+import (
+	"github.com/veteran-software/discord-api-wrapper/v10/api"
+)
+
+// ApplicationCommandPermissionsUpdate - APPLICATION_COMMAND_PERMISSIONS_UPDATE event, sent when an application command's permissions are updated.
+//
+// The inner payload is an application command permissions object.
+type (
+	ApplicationCommandPermissionsUpdate api.ApplicationCommandPermissions
+)

gateway/events/receive/automod/events.go

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2023. Veteran Software
+ *
+ * Discord API Wrapper - A custom wrapper for the Discord REST API developed for a proprietary project.
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
+ * License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later
+ * version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program.
+ * If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package automod
+
+import (
+	"github.com/veteran-software/discord-api-wrapper/v10/api"
+)
+
+/* AUTO MODERATION */
+
+// All Auto Moderation related events are only sent to bot users which have the MANAGE_GUILD permission.
+type (
+	// AutoModerationRuleCreate - Sent when a rule is created. The inner payload is an auto moderation rule object.
+	AutoModerationRuleCreate api.AutoModerationRule
+
+	// AutoModerationRuleUpdate - Sent when a rule is updated. The inner payload is an auto moderation rule object.
+	AutoModerationRuleUpdate api.AutoModerationRule
+
+	// AutoModerationRuleDelete - Sent when a rule is deleted. The inner payload is an auto moderation rule object.
+	AutoModerationRuleDelete api.AutoModerationRule
+
+	// AutoModerationRuleExecution - Sent when a rule is triggered and an action is executed (e.g. when a message is blocked).
+	AutoModerationRuleExecution struct {
+		GuildID              api.Snowflake     `json:"guild_id"`
+		Action               api.AutoModAction `json:"action"`
+		RuleID               api.Snowflake     `json:"rule_id"`
+		RuleTriggerType      api.TriggerType   `json:"rule_trigger_type"`
+		UserID               api.Snowflake     `json:"user_id"`
+		ChannelID            api.Snowflake     `json:"channel_id,omitempty"`
+		MessageID            api.Snowflake     `json:"message_id"`
+		AlertSystemMessageID api.Snowflake     `json:"alert_system_message_id"`
+		Content              string            `json:"content,omitempty"` // MESSAGE_CONTENT (1 << 15) gateway intent is required to receive the `content` and `matched_content` fields
+		MatchedKeyword       *string           `json:"matched_keyword"`
+		MatchedContent       *string           `json:"matched_content"` // MESSAGE_CONTENT (1 << 15) gateway intent is required to receive the `content` and `matched_content` fields
+	}
+)

gateway/events/receive/channels/events.go

@@ -0,0 +1,100 @@
+/*
+ * Copyright (c) 2023. Veteran Software
+ *
+ * Discord API Wrapper - A custom wrapper for the Discord REST API developed for a proprietary project.
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
+ * License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later
+ * version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program.
+ * If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package channels
+
+import (
+	"time"
+
+	"github.com/veteran-software/discord-api-wrapper/v10/api"
+)
+
+/* CHANNELS */
+
+type (
+	// ChannelCreate - Sent when a new guild channel is created, relevant to the current user. The inner payload is a channel object.
+	ChannelCreate api.Channel
+
+	// ChannelUpdate - Sent when a channel is updated.
+	//
+	// The inner payload is a channel object.
+	//
+	// This is not sent when the field last_message_id is altered.
+	//
+	// To keep track of the last_message_id changes, you must listen for Message Create events (or Thread Create events for GUILD_FORUM channels).
+	//
+	//This event may reference roles or guild members that no longer exist in the guild.
+	ChannelUpdate api.Channel
+
+	// ChannelDelete - Sent when a channel relevant to the current user is deleted. The inner payload is a channel object.
+	ChannelDelete api.Channel
+
+	// ThreadCreate - Sent when a thread is created, relevant to the current user, or when the current user is added to a thread.
+	// The inner payload is a channel object.
+	//
+	//    When a thread is created, includes an additional newly_created boolean field.
+	//    When being added to an existing private thread, includes a thread member object.
+	ThreadCreate api.Channel
+
+	// ThreadUpdate - Sent when a thread is updated.
+	// The inner payload is a channel object.
+	// This is not sent when the field last_message_id is altered.
+	// To keep track of the last_message_id changes, you must listen for Message Create events.
+	ThreadUpdate api.Channel
+
+	// ThreadDelete - Sent when a thread relevant to the current user is deleted.
+	// The inner payload is a subset of the channel object, containing just the `id`, `guild_id`, `parent_id`, and `type` fields.
+	ThreadDelete api.Channel
+
+	// ThreadListSync - Sent when the current user gains access to a channel.
+	ThreadListSync struct {
+		GuildID    api.Snowflake      `json:"guild_id"`              // ID of the guild
+		ChannelIDS []api.Snowflake    `json:"channel_ids,omitempty"` // Parent channel IDs whose threads are being synced. If omitted, then threads were synced for the entire guild. This array may contain channel_ids that have no active threads as well, so you know to clear that data.
+		Threads    []api.Channel      `json:"threads"`               // All active threads in the given channels that the current user can access
+		Members    []api.ThreadMember `json:"members"`               // All thread member objects from the synced threads for the current user, indicating which threads the current user has been added to
+	}
+
+	// ThreadMemberUpdate - Sent when the thread member object for the current user is updated.
+	// The inner payload is a thread member object with an extra guild_id field.
+	// This event is documented for completeness, but unlikely to be used by most bots.
+	//
+	// For bots, this event largely is just a signal that you are a member of the thread.
+	ThreadMemberUpdate struct {
+		api.ThreadMember
+		GuildID api.Snowflake `json:"guild_id,omitempty"` // 	ID of the guild
+	}
+
+	// ThreadMembersUpdate - Sent when anyone is added to or removed from a thread.
+	// If the current user does not have the GUILD_MEMBERS Gateway Intent, then this event will only be sent if the current user was added to or removed from the thread.
+	ThreadMembersUpdate struct {
+		ID           api.Snowflake `json:"id"`
+		GuildID      api.Snowflake `json:"guild_id"`
+		MemberCount  uint8         `json:"member_count"`
+		AddedMembers []struct {
+			api.ThreadMember
+			GuildMember api.GuildMember `json:"guild_member,omitempty"`
+		} `json:"added_members,omitempty"`
+		RemovedMemberIDS []api.Snowflake `json:"removed_member_ids,omitempty"`
+	}
+
+	// ChannelPinsUpdate - Sent when a message is pinned or unpinned in a text channel.
+	// This is not sent when a pinned message is deleted.
+	ChannelPinsUpdate struct {
+		GuildID          api.Snowflake `json:"guild_id,omitempty"`
+		ChannelID        api.Snowflake `json:"channel_id"`
+		LastPinTimestamp *time.Time    `json:"last_pin_timestamp,omitempty"`
+	}
+)

gateway/events/receive/events.go

@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) 2023. Veteran Software
+ *
+ * Discord API Wrapper - A custom wrapper for the Discord REST API developed for a proprietary project.
+ *
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public
+ * License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later
+ * version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
+ * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along with this program.
+ * If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package receive
+
+import (
+	"github.com/veteran-software/discord-api-wrapper/v10/api"
+)
+
+// Hello - Sent on connection to the websocket. Defines the heartbeat interval that the client should heartbeat to.
+type Hello struct {
+	HeartbeatInterval int      `json:"heartbeat_interval"` // the interval (in milliseconds) the client should heartbeat with
+	Trace             []string `json:"_trace,omitempty"`   // Sent from the gateway but unused & undocumented
+}
+
+// Ready - The ready event is dispatched when a client has completed the initial handshake with the gateway (for new sessions).
+//
+// The ready event can be the largest and most complex event the gateway will send, as it contains all the state required for a client to begin interacting with the rest of the platform.
+//
+// `guilds` are the guilds of which your bot is a member.
+//
+// They start out as unavailable when you connect to the gateway.
+//
+// As they become available, your bot will be notified via Guild Create events.
+type Ready struct {
+	V                int                     `json:"v"`                  // gateway version
+	User             api.User                `json:"user"`               // information about the user including email
+	Guilds           []*api.UnavailableGuild `json:"guilds"`             // the guilds the user is in
+	SessionID        string                  `json:"session_id"`         // used for resuming connections
+	ResumeGatewayURL string                  `json:"resume_gateway_url"` // Gateway URL for resuming connections
+	Shard            [2]int                  `json:"shard,omitempty"`    // the shard information associated with this session, if sent when identifying
+	Application      api.Application         `json:"application"`        // contains id and flags
+}
+
+// Reconnect - The reconnect event is dispatched when a client should reconnect to the gateway (and resume their existing session, if they have one).
+//
+// This event usually occurs during deploys to migrate sessions gracefully off old hosts.
+type Reconnect struct {
+	Op int `json:"op"`
+	D  any `json:"d"`
+}
+
+// InvalidSession - Sent to indicate one of at least three different situations:
+//
+//	the gateway could not initialize a session after receiving an Opcode 2 Identify
+//	the gateway could not resume a previous session after receiving an Opcode 6 Resume
+//	the gateway has invalidated an active session and is requesting client action
+//
+// The inner `d` key is a boolean that indicates whether the session may be resumable.
+type InvalidSession struct {
+	Op int  `json:"op"`
+	D  bool `json:"d"`
+}