From 9c7c0986d7aaa9cf5427e62b7a271a43982d9a74 Mon Sep 17 00:00:00 2001
From: Kegan Dougal <kegan@matrix.org>
Date: Fri, 9 Dec 2016 15:03:19 +0000
Subject: [PATCH] Add Login()

With example.
---
 client.go               | 12 ++++++++++++
 client_examples_test.go | 15 ++++++++++++++-
 requests.go             | 12 ++++++++++++
 responses.go            |  8 ++++++++
 4 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/client.go b/client.go
index 6d4a19f..a0eaf33 100644
--- a/client.go
+++ b/client.go
@@ -343,6 +343,18 @@ func (cli *Client) RegisterDummy(req *ReqRegister, setOnClient bool) (*RespRegis
 	return res, nil
 }
 
+// Login a user to the homeserver according to http://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-client-r0-login
+// If 'setOnClient' is true, the user ID and access token on login will be set to this client instance.
+func (cli *Client) Login(req *ReqLogin, setOnClient bool) (resp *RespLogin, err error) {
+	urlPath := cli.BuildURL("login")
+	_, err = cli.MakeRequest("POST", urlPath, req, &resp)
+	if setOnClient && resp != nil {
+		cli.UserID = resp.UserID
+		cli.AccessToken = resp.AccessToken
+	}
+	return
+}
+
 // JoinRoom joins the client to a room ID or alias. See http://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-client-r0-join-roomidoralias
 //
 // If serverName is specified, this will be added as a query param to instruct the homeserver to join via that server. If content is specified, it will
diff --git a/client_examples_test.go b/client_examples_test.go
index 0d98022..775e58b 100644
--- a/client_examples_test.go
+++ b/client_examples_test.go
@@ -27,7 +27,7 @@ func ExampleClient_BuildBaseURL() {
 	// Output: https://matrix.org/_matrix/client/r0/directory/room/%23matrix:matrix.org?access_token=abcdef123456
 }
 
-// Compiled, not run.
+// Retrieve the content of a m.room.name state event.
 func ExampleClient_StateEvent() {
 	content := struct {
 		name string `json:"name"`
@@ -37,3 +37,16 @@ func ExampleClient_StateEvent() {
 		panic(err)
 	}
 }
+
+// Login to a local homeserver. This will set Client.UserID and Client.AccessToken on success.
+func ExampleClient_Login() {
+	cli, _ := NewClient("http://localhost:8008", "", "")
+	_, err := cli.Login(&ReqLogin{
+		Type:     "m.login.password",
+		User:     "alice",
+		Password: "wonderland",
+	}, true)
+	if err != nil {
+		panic(err)
+	}
+}
diff --git a/requests.go b/requests.go
index 8e236f3..0b47ec3 100644
--- a/requests.go
+++ b/requests.go
@@ -9,3 +9,15 @@ type ReqRegister struct {
 	InitialDeviceDisplayName string      `json:"initial_device_display_name"`
 	Auth                     interface{} `json:"auth,omitempty"`
 }
+
+// ReqLogin is the JSON request for http://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-client-r0-login
+type ReqLogin struct {
+	Type                     string `json:"type"`
+	Password                 string `json:"password,omitempty"`
+	Medium                   string `json:"medium,omitempty"`
+	User                     string `json:"user,omitempty"`
+	Address                  string `json:"address,omitempty"`
+	Token                    string `json:"token,omitempty"`
+	DeviceID                 string `json:"device_id,omitempty"`
+	InitialDeviceDisplayName string `json:"initial_device_display_name,omitempty"`
+}
diff --git a/responses.go b/responses.go
index e086824..67f3bd5 100644
--- a/responses.go
+++ b/responses.go
@@ -66,6 +66,14 @@ type RespRegister struct {
 	UserID       string `json:"user_id"`
 }
 
+// RespLogin is the JSON response for http://matrix.org/docs/spec/client_server/r0.2.0.html#post-matrix-client-r0-login
+type RespLogin struct {
+	AccessToken string `json:"access_token"`
+	DeviceID    string `json:"device_id"`
+	HomeServer  string `json:"home_server"`
+	UserID      string `json:"user_id"`
+}
+
 // RespSync is the JSON response for http://matrix.org/docs/spec/client_server/r0.2.0.html#get-matrix-client-r0-sync
 type RespSync struct {
 	NextBatch   string `json:"next_batch"`