Add personal access token login method

README.md

@@ -122,7 +122,7 @@ puts "Rocket.Chat version: #{info.version}"
 ```
 
 #### authentication
-To logout from a server:
+With username and password
 
 ```ruby
 require 'rocketchat'
@@ -133,6 +133,17 @@ session = rocket_server.login('username', 'password')
 session.logout
 ```
 
+With user ID and personal access token (PAT) obtained from `https://your.server.address/account/tokens`
+
+```ruby
+require 'rocketchat'
+
+rocket_server = RocketChat::Server.new('http://your.server.address/')
+session = rocket_server.login_with_token('user-id', 'pat')
+# ... use the API ...
+# Logout not required
+```
+
 #### debugging
 To debug the communications between the gem and Rocket.Chat, there is a debug option.
 It accepts a stream for logging.

lib/rocket_chat/server.rb

@@ -48,6 +48,25 @@ def login(username, password)
       Session.new self, Token.new(response['data'])
     end
 
+    #
+    # Login with personal access token (PAT) to the REST API
+    #
+    # Get user ID and PAT from https://your.server.address/account/tokens.
+    # @param [String] user_id User ID
+    # @param [String] auth_token Token
+    # @return [Session] Rocket.Chat Session
+    # @raise [HTTPError, StatusError]
+    #
+    def login_with_token(user_id, auth_token)
+      session = Session.new self, Token.new(userId: user_id, authToken: auth_token)
+      # Call `me` endpoint to validate credentials. Raises StatusError for
+      # invalid credentials.
+      session.me
+      session
+    rescue StatusError => e
+      raise e.exception('Invalid credentials')
+    end
+
     def request_json(path, options = {})
       super(path, @options.merge(options))
     end

spec/rocket_chat/server_spec.rb

@@ -83,4 +83,50 @@
       end
     end
   end
+
+  describe '#login_with_token' do
+    before do
+      stub_request(:get, "#{SERVER_URI}api/v1/me").to_return(
+        body: {
+          status: :error,
+          message: 'You must be logged in to do this.'
+        }.to_json,
+        status: 401
+      )
+
+      stub_request(:get, "#{SERVER_URI}api/v1/me")
+        .with(headers: { 'X-Auth-Token' => AUTH_TOKEN, 'X-User-Id' => USER_ID })
+        .to_return(
+          body: {
+            status: :success,
+            data: { _id: USER_ID }
+          }.to_json,
+          status: 200
+        )
+    end
+
+    context 'with valid credentials' do
+      it 'returns a new session' do
+        rc = server.login_with_token(USER_ID, AUTH_TOKEN)
+        expect(rc.token.auth_token).to eq AUTH_TOKEN
+        expect(rc.token.user_id).to eq USER_ID
+      end
+    end
+
+    context 'with invalid user id' do
+      it 'raises a status error' do
+        expect do
+          server.login_with_token('invalid-user-id', AUTH_TOKEN)
+        end.to raise_error RocketChat::StatusError, 'Invalid credentials'
+      end
+    end
+
+    context 'with invalid auth token' do
+      it 'raises a status error' do
+        expect do
+          server.login_with_token(USER_ID, 'invalid-auth-token')
+        end.to raise_error RocketChat::StatusError, 'Invalid credentials'
+      end
+    end
+  end
 end