Class: Chatrix::Api::Users

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

Overview

Contains methods to use user 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

#get(user) ⇒ Hash

Gets information about a specific user.

Examples:

Print a user's display name

puts get_user('@foo:matrix.org')['displayname']

Raises:



18
19
20
21
22
23
 
# File 'lib/chatrix/api/users.rb', line 18

def get(user)
  make_request(:get, "/profile/#{user}").parsed_response
rescue NotFoundError => e
  raise UserNotFoundError.new(user, e.error),
        'The specified user could not be found'
end

#get_avatar(user) ⇒ String

Get the URL to a user's avatar (an mxp:// URL).

Raises:



30
31
32
33
34
35
 
# File 'lib/chatrix/api/users.rb', line 30

def get_avatar(user)
  make_request(:get, "/profile/#{user}/avatar_url")['avatar_url']
rescue NotFoundError => e
  raise AvatarNotFoundError.new(user, e.error),
        'Avatar or user could not be found'
end

#get_displayname(user) ⇒ String

Get a user's display name (not username).



56
57
58
59
60
61
 
# File 'lib/chatrix/api/users.rb', line 56

def get_displayname(user)
  make_request(:get, "/profile/#{user}/displayname")['displayname']
rescue NotFoundError => e
  raise UserNotFoundError.new(user, e.error),
        'The specified user could not be found'
end

#get_presence_list(user) ⇒ Array

TODO:

The official documentation on this endpoint is weird, what does this really do?

Gets the presence list for a user.



116
117
118
 
# File 'lib/chatrix/api/users.rb', line 116

def get_presence_list(user)
  make_request(:get, "/presence/list/#{user}").parsed_response
end

#get_presence_status(user) ⇒ Hash

Gets the presence status of a user.



154
155
156
 
# File 'lib/chatrix/api/users.rb', line 154

def get_presence_status(user)
  make_request(:get, "/presence/#{user}/status").parsed_response
end

#set_avatar(user, avatar) ⇒ Boolean

Sets a new avatar for a user.



43
44
45
46
47
48
49
 
# File 'lib/chatrix/api/users.rb', line 43

def set_avatar(user, avatar)
  make_request(
    :put,
    "/profile/#{user}/avatar_url",
    content: { avatar_url: avatar }
  ).code == 200
end

#set_data(user, type, data) ⇒ Boolean

Sets account data for a user.



87
88
89
90
91
92
93
 
# File 'lib/chatrix/api/users.rb', line 87

def set_data(user, type, data)
  make_request(
    :put,
    "/user/#{user}/account_data/#{type}",
    content: data
  ).code == 200
end

#set_displayname(user, displayname) ⇒ Boolean

Note:

Can only be used on the user who possesses the access_token currently in use.

Sets a new display name for a user.



72
73
74
75
76
77
78
 
# File 'lib/chatrix/api/users.rb', line 72

def set_displayname(user, displayname)
  make_request(
    :put,
    "/profile/#{user}/displayname",
    content: { displayname: displayname }
  ).code == 200
end

#set_room_data(user, room, type, data) ⇒ Boolean

Sets account data for a user specific to a certain room.



101
102
103
104
105
106
107
 
# File 'lib/chatrix/api/users.rb', line 101

def set_room_data(user, room, type, data)
  make_request(
    :put,
    "/user/#{user}/rooms/#{room}/account_data/#{type}",
    content: data
  ).code == 200
end

#update_presence_list(user, data) ⇒ Boolean

Adds or removes users from a user's presence list.

Examples:

Add and remove two users

update_presence_list(
  '@me:home.org',
  {
    invite: ['@friend:home.org'],
    drop: ['@enemy:other.org']
  }
)



140
141
142
143
144
145
146
 
# File 'lib/chatrix/api/users.rb', line 140

def update_presence_list(user, data)
  make_request(
    :post,
    "/presence/list/#{user}",
    content: { presence_diff: data }
  ).code == 200
end

#update_presence_status(user, status, message = nil) ⇒ Boolean

Note:

Only the user for whom the access_token is valid for can have their presence updated.

Updates the presence status of a user.



170
171
172
173
174
175
176
177
 
# File 'lib/chatrix/api/users.rb', line 170

def update_presence_status(user, status, message = nil)
  content = { presenceState: { presence: status } }

  content[:presenceState][:status_msg] = message if message

  make_request(:put, "/presence/#{user}/status", content: content)
    .code == 200
end