Class: Chatrix::Api::Session

Inherits:
ApiComponent show all
Defined in:
lib/chatrix/api/session.rb

Overview

Contains methods to use session related endpoints in the API.

Instance Method Summary collapse

Methods inherited from ApiComponent

#initialize, #make_request

Constructor Details

This class inherits a constructor from Chatrix::Api::ApiComponent

Instance Method Details

#add_threepid(data) ⇒ Boolean

Adds third-party identification information to the user account.

Parameters:

  • data (Hash) —

    The data to add. Refer to the official documentation for more information.

Returns:

  • (Boolean) —

    true if the information was added successfully, otherwise false.



21
22
23
 
# File 'lib/chatrix/api/session.rb', line 21

def add_threepid(data)
  make_request(:post, '/account/3pid', content: data).code == 200
end

#login(method, options) ⇒ Hash

Note:

A successful login will update the access_token to the new one returned from the login response.

Performs a login attempt.

Examples:

Logging in with username and password

('m.login.password',
      user: '@snoo:reddit.com', password: 'hunter2')

Parameters:

  • method (String) —

    The method to use for logging in. For user/password combination, this should be m.login.password.

  • options (Hash{String=>String}) —

    Options to pass for logging in. For a password login, this should contain a key :user for the username, and a key :password for the password.

Returns:

  • (Hash) —

    The response from the server. A successful login will return a hash containing the user id, access token, and homeserver.



99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/chatrix/api/session.rb', line 99

def (method, options)
  response = make_request(
    :post,
    '/login',
    content: { type: method }.merge!(options)
  )

  # Update the local access token
  @matrix.access_token = response['access_token']

  response.parsed_response
end

#logout ⇒ Boolean

Note:

This will invalidate the access token. It will no longer be valid for further API calls.

Logs out.

Returns:

  • (Boolean) —

    true if the user was successfully logged out, otherwise false.



119
120
121
122
123
124
125
126
 
# File 'lib/chatrix/api/session.rb', line 119

def logout
  response = make_request :post, '/logout'

  # A successful logout means the access token has been invalidated
  @matrix.access_token = nil

  response.code == 200
end

#refresh(token = nil) ⇒ Hash

Note:

On success, the internal access_token and refresh_token will be updated automatically for use in subsequent API calls.

Gets a new access token to use for API calls when the current one expires.

Parameters:

  • token (String, nil) (defaults to: nil) —

    The refresh_token to provide for the server when requesting a new token. If not set, the internal refresh and access tokens will be used.

Returns:

  • (Hash) —

    The response hash from the server will contain the new access token and a refresh token to use the next time a new access token is needed.



141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/chatrix/api/session.rb', line 141

def refresh(token = nil)
  refresh_token = token || @refresh_token || @access_token

  response = make_request(
    :post,
    '/tokenrefresh',
    content: { refresh_token: refresh_token }
  )

  @matrix.access_token = response['access_token']
  @refresh_token = response['refresh_token']

  response.parsed_response
end

#register(data, kind = 'user') ⇒ Hash

Note:

On a successful registration, the access_token and refresh_token will be updated to the values returned by the server.

Registers a new user on the homeserver.

Parameters:

  • data (Hash) —

    Registration data. Populate this with the information needed to register the new user.

    Refer to the official API documentation on how to populate the data hash.

  • kind (String) (defaults to: 'user') —

    The kind of registration to make. Either 'guest' or 'user'.

Returns:

  • (Hash) —

    On success, returns a hash with information about the newly registered user. An example return value is given below.

    {
  'user_id' => '@foo:bar.org',
  'home_server' => 'https://bar.org',
  'access_token' => 'some secret token',
  'refresh_token' => 'refresh token here'
}



68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/chatrix/api/session.rb', line 68

def register(data, kind = 'user')
  response = make_request(
    :post,
    '/register',
    params: { kind: kind },
    content: data
  )

  @matrix.access_token = response['access_token']
  @refresh_token = response['refresh_token']

  response.parsed_response
end

#set_password(password, auth = nil) ⇒ Boolean

Note:

The server may request additional authentication as per the official documentation on the "User-Interactive Authentication API".

Set a new password for the current account.

Parameters:

  • password (String) —

    The new password to set.

  • auth (Hash, nil) (defaults to: nil) —

    If provided, the hash will be passed in the request as additional parameters inside the auth field.

Returns:

  • (Boolean) —

    true if the password was successfully changed, otherwise false.



35
36
37
38
39
40
 
# File 'lib/chatrix/api/session.rb', line 35

def set_password(password, auth = nil)
  data = { new_password: password }
  data[:auth] = auth if auth

  make_request(:post, '/account/password', content: data).code == 200
end

#threepids ⇒ Array

Gets third-party IDs associated with the current account.

Returns:

  • (Array) —

    A list of 3rd party IDs.



12
13
14
 
# File 'lib/chatrix/api/session.rb', line 12

def threepids
  make_request(:get, '/account/3pid')['threepids']
end