Merge pull request #91 from iopred/login

BREAKING - Add a new optional token to New, which is a cheaper way to login. Closes #89.

discord.go

@@ -20,9 +20,15 @@ const VERSION = "0.10.0-alpha"
 
 // New creates a new Discord session and will automate some startup
 // tasks if given enough information to do so.  Currently you can pass zero
-// arguments and it will return an empty Discord session. If you pass a token
-// or username and password (in that order), then it will attempt to login to
-// Discord and open a websocket connection.
+// arguments and it will return an empty Discord session.
+// There are 3 ways to call New:
+//     With a single auth token - All requests will use the token blindly,
+//         no verification of the token will be done and requests may fail.
+//     With an email and password - Discord will sign in with the provided
+//         credentials.
+//     With an email, password and auth token - Discord will verify the auth
+//         token, if it is invalid it will sign in with the provided
+//         credentials. This is the Discord recommended way to sign in.
 func New(args ...interface{}) (s *Session, err error) {
 
 	// Create an empty Session interface.
@@ -46,7 +52,7 @@ func New(args ...interface{}) (s *Session, err error) {
 		switch v := arg.(type) {
 
 		case []string:
-			if len(v) > 2 {
+			if len(v) > 3 {
 				err = fmt.Errorf("Too many string parameters provided.")
 				return
 			}
@@ -61,6 +67,11 @@ func New(args ...interface{}) (s *Session, err error) {
 				pass = v[1]
 			}
 
+			// If third string exists, it must be an auth token.
+			if len(v) > 2 {
+				s.Token = v[2]
+			}
+
 		case string:
 			// First string must be either auth token or username.
 			// Second string must be a password.
@@ -70,6 +81,8 @@ func New(args ...interface{}) (s *Session, err error) {
 				auth = v
 			} else if pass == "" {
 				pass = v
+			} else if s.Token == "" {
+				s.Token = v
 			} else {
 				err = fmt.Errorf("Too many string parameters provided.")
 				return
@@ -85,11 +98,13 @@ func New(args ...interface{}) (s *Session, err error) {
 	}
 
 	// If only one string was provided, assume it is an auth token.
-	// Otherwise get auth token from Discord
+	// Otherwise get auth token from Discord, if a token was specified
+	// Discord will verify it for free, or log the user in if it is
+	// invalid.
 	if pass == "" {
 		s.Token = auth
 	} else {
-		s.Token, err = s.Login(auth, pass)
+		err = s.Login(auth, pass)
 		if err != nil || s.Token == "" {
 			err = fmt.Errorf("Unable to fetch discord authentication token. %v", err)
 			return

examples/api_basic/api_basic.go

@@ -28,7 +28,7 @@ func main() {
 	}
 
 	// Login to the Discord server and store the authentication token
-	dg.Token, err = dg.Login(os.Args[1], os.Args[2])
+	err = dg.Login(os.Args[1], os.Args[2])
 	if err != nil {
 		fmt.Println(err)
 		return

restapi.go

@@ -128,8 +128,8 @@ func unmarshal(data []byte, v interface{}) error {
 // Functions specific to Discord Sessions
 // ------------------------------------------------------------------------------------------------
 
-// Login asks the Discord server for an authentication token
-func (s *Session) Login(email string, password string) (token string, err error) {
+// Login asks the Discord server for an authentication token.
+func (s *Session) Login(email, password string) (err error) {
 
 	data := struct {
 		Email    string `json:"email"`
@@ -150,7 +150,7 @@ func (s *Session) Login(email string, password string) (token string, err error)
 		return
 	}
 
-	token = temp.Token
+	s.Token = temp.Token
 	return
 }