Module: MatrixSdk::Protocols::CS

Included in:
Api
Defined in:
lib/matrix_sdk/protocols/cs.rb

Instance Method Summary collapse

Instance Method Details

#add_user_tag(user_id, room_id, tag, **params) ⇒ Object 



638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 638

def add_user_tag(user_id, room_id, tag, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  if params[:body]
    content = params[:body]
  else
    content = {}
    content[:order] = params[:order] if params.key? :order
  end

  room_id = ERB::Util.url_encode room_id.to_s
  user_id = ERB::Util.url_encode user_id.to_s
  tag = ERB::Util.url_encode tag.to_s

  request(:put, :client_r0, "/user/#{user_id}/rooms/#{room_id}/tags/#{tag}", body: content, query: query)
end

#allowed_login_methods ⇒ Object 



28
29
30
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 28

def 
  request(:get, :client_r0, '/login').flows
end

#ban_user(room_id, user_id, reason: '', **params) ⇒ Object 



592
593
594
595
596
597
598
599
600
601
602
603
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 592

def ban_user(room_id, user_id, reason: '', **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    user_id: user_id,
    reason: reason
  }
  room_id = ERB::Util.url_encode room_id.to_s

  request(:post, :client_r0, "/rooms/#{room_id}/ban", body: content, query: query)
end

#client_api_unstable_features ⇒ Array

Gets the list of available unstable client API features

Returns:

  • (Array) 


18
19
20
21
22
23
24
25
26
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 18

def client_api_unstable_features
  @client_api_unstable_features ||= request(:get, :client, '/versions').unstable_features.tap do |vers|
    vers.instance_eval <<-'CODE', __FILE__, __LINE__ + 1
      def has?(feature)
        fetch(feature, nil)
      end
    CODE
  end
end

#client_api_versions ⇒ Array

Gets the available client API versions

Returns:

  • (Array) 


6
7
8
9
10
11
12
13
14
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 6

def client_api_versions
  @client_api_versions ||= request(:get, :client, '/versions').versions.tap do |vers|
    vers.instance_eval <<-'CODE', __FILE__, __LINE__ + 1
      def latest
        last
      end
    CODE
  end
end

#create_filter(user_id, filter_params, **params) ⇒ Object 



708
709
710
711
712
713
714
715
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 708

def create_filter(user_id, filter_params, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s

  request(:post, :client_r0, "/user/#{user_id}/filter", body: filter_params, query: query)
end

#create_room(visibility: :public, **params) ⇒ Response

Creates a new room

Parameters:

  • params (Hash) —

    The room creation details

Options Hash (**params):

  • :visibility (Symbol) — default: :public —

    The room visibility

  • :room_alias (String) —

    A room alias to apply on creation

  • :invite (Boolean) —

    Should the room be created invite-only

Returns:

  • (Response) —

    A response hash with …

See Also:



206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 206

def create_room(visibility: :public, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    visibility: visibility
  }
  content[:room_alias_name] = params.delete(:room_alias) if params[:room_alias]
  content[:invite] = [params.delete(:invite)].flatten if params[:invite]
  content.merge! params

  request(:post, :client_r0, '/createRoom', body: content, query: query)
end

#delete_device(device_id, auth:) ⇒ Object 



859
860
861
862
863
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 859

def delete_device(device_id, auth:)
  device_id = ERB::Util.url_encode device_id.to_s

  request(:delete, :client_r0, "/devices/#{device_id}", body: { auth: auth })
end

#forget_room(room_id, **params) ⇒ Object 



536
537
538
539
540
541
542
543
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 536

def forget_room(room_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s

  request(:post, :client_r0, "/rooms/#{room_id}/forget", query: query)
end

#get_account_data(user_id, type_key, **params) ⇒ Object 



656
657
658
659
660
661
662
663
664
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 656

def (user_id, type_key, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s
  type_key = ERB::Util.url_encode type_key.to_s

  request(:get, :client_r0, "/user/#{user_id}/account_data/#{type_key}", query: query)
end

#get_avatar_url(user_id, **params) ⇒ Object 



746
747
748
749
750
751
752
753
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 746

def get_avatar_url(user_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s

  request(:get, :client_r0, "/profile/#{user_id}/avatar_url", query: query)
end

#get_device(device_id) ⇒ Object 



847
848
849
850
851
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 847

def get_device(device_id)
  device_id = ERB::Util.url_encode device_id.to_s

  request(:get, :client_r0, "/devices/#{device_id}")
end

#get_devices ⇒ Object 



843
844
845
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 843

def get_devices
  request(:get, :client_r0, '/devices')
end

#get_display_name(user_id, **params) ⇒ Object 



724
725
726
727
728
729
730
731
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 724

def get_display_name(user_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s

  request(:get, :client_r0, "/profile/#{user_id}/displayname", query: query)
end

#get_download_url(mxcurl, **_params) ⇒ Object 



777
778
779
780
781
782
783
784
785
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 777

def get_download_url(mxcurl, **_params)
  mxcurl = URI.parse(mxcurl.to_s) unless mxcurl.is_a? URI
  raise 'Not a mxc:// URL' unless mxcurl.is_a? URI::MATRIX

  homeserver.dup.tap do |u|
    full_path = ERB::Util.url_encode mxcurl.full_path.to_s
    u.path = "/_matrix/media/r0/download/#{full_path}"
  end
end

#get_filter(user_id, filter_id, **params) ⇒ Object 



698
699
700
701
702
703
704
705
706
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 698

def get_filter(user_id, filter_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s
  filter_id = ERB::Util.url_encode filter_id.to_s

  request(:get, :client_r0, "/user/#{user_id}/filter/#{filter_id}", query: query)
end

#get_joined_rooms(**params) ⇒ Response

Gets the list of rooms joined by the current user

Returns:

  • (Response) —

    An array of room IDs under the key :joined_rooms

See Also:



158
159
160
161
162
163
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 158

def get_joined_rooms(**params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  request(:get, :client_r0, '/joined_rooms', query: query)
end

#get_membership(room_id, user_id, **params) ⇒ Object 



571
572
573
574
575
576
577
578
579
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 571

def get_membership(room_id, user_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s
  user_id = ERB::Util.url_encode user_id.to_s

  request(:get, :client_r0, "/rooms/#{room_id}/state/m.room.member/#{user_id}", query: query)
end

#get_power_levels(room_id, **params) ⇒ Object 



518
519
520
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 518

def get_power_levels(room_id, **params)
  get_room_state(room_id, 'm.room.power_levels', params)
end

#get_profile(user_id, **params) ⇒ Object 



768
769
770
771
772
773
774
775
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 768

def get_profile(user_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s

  request(:get, :client_r0, "/profile/#{user_id}", query: query)
end

#get_public_rooms(server: nil, **params) ⇒ Response

Gets the list of public rooms on a Matrix server

Parameters:

  • limit (Integer) —

    Limits the number of results returned

  • since (String) —

    A pagination token received from an earlier call

  • server (String) (defaults to: nil) —

    The Matrix server to request public rooms from

Returns:

  • (Response) —

    An array of public rooms in the :chunk key, along with :next_batch, :prev_batch, and :total_room_count_estimate for pagination

See Also:



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 175

def get_public_rooms(server: nil, **params)
  query = {
    server: server
  }.compact
  body = nil
  method = :get

  if !params[:filter].nil? || !params[:include_all_networks].nil? || !params[:third_party_instance_id].nil?
    body = {
      limit: params[:limit],
      since: params[:since],
      filter: params[:filter],
      include_all_networks: params[:include_all_networks],
      third_party_instance_id: params[:third_party_instance_id]
    }.merge(params).compact
    method = :post
  else
    query = query.merge(params).compact
  end

  request(method, :client_r0, '/publicRooms', query: query, body: body)
end

#get_room_account_data(user_id, room_id, type_key, **params) ⇒ Object 



676
677
678
679
680
681
682
683
684
685
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 676

def (user_id, room_id, type_key, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s
  room_id = ERB::Util.url_encode room_id.to_s
  type_key = ERB::Util.url_encode type_key.to_s

  request(:get, :client_r0, "/user/#{user_id}/rooms/#{room_id}/account_data/#{type_key}", query: query)
end

#get_room_id(room_alias, **params) ⇒ Object 



787
788
789
790
791
792
793
794
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 787

def get_room_id(room_alias, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_alias = ERB::Util.url_encode room_alias.to_s

  request(:get, :client_r0, "/directory/room/#{room_alias}", query: query)
end

#get_room_members(room_id, **params) ⇒ Object 



817
818
819
820
821
822
823
824
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 817

def get_room_members(room_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s

  request(:get, :client_r0, "/rooms/#{room_id}/members", query: query)
end

#get_room_messages(room_id, token, direction, limit: 10, **params) ⇒ Response

Retrieve additional messages in a room

Parameters:

  • room_id (MXID, String) —

    The room ID to retrieve messages for

  • token (String) —

    The token to start retrieving from, can be from a sync or from an earlier get_room_messages call

  • direction (:b, :f) —

    The direction to retrieve messages

  • limit (Integer) (defaults to: 10) —

    (10) The limit of messages to retrieve

  • params (Hash) —

    Additional options for the request

Options Hash (**params):

  • :to (String) —

    A token to limit retrieval to

  • :filter (String) —

    A filter to limit the retrieval to

Returns:

  • (Response) —

    A response hash with the message information containing :start, :end, and :chunk fields

See Also:



456
457
458
459
460
461
462
463
464
465
466
467
468
469
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 456

def get_room_messages(room_id, token, direction, limit: 10, **params)
  query = {
    from: token,
    dir: direction,
    limit: limit
  }
  query[:to] = params[:to] if params.key? :to
  query[:filter] = params.fetch(:filter) if params.key? :filter
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s

  request(:get, :client_r0, "/rooms/#{room_id}/messages", query: query)
end

#get_room_name(room_id, **params) ⇒ Response

Gets the display name of a room

Parameters:

  • room_id (MXID, String) —

    The room ID to look up

Returns:

  • (Response) —

    A response hash with the parameter :name

See Also:



496
497
498
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 496

def get_room_name(room_id, **params)
  get_room_state(room_id, 'm.room.name', params)
end

#get_room_state(room_id, state_type = nil, key: nil, **params) ⇒ Response

Reads the latest instance of a room state event

Parameters:

  • room_id (MXID, String) —

    The room ID to read from

  • state_type (String) (defaults to: nil) —

    The state type to read

Returns:

  • (Response) —

    A response hash with the contents of the state event

See Also:



478
479
480
481
482
483
484
485
486
487
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 478

def get_room_state(room_id, state_type = nil, key: nil, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s
  state_type = ERB::Util.url_encode state_type.to_s
  key = ERB::Util.url_encode key.to_s

  request(:get, :client_r0, "/rooms/#{room_id}/state#{state_type.empty? ? nil : "/#{state_type}"}#{key.empty? ? nil : "/#{key}"}", query: query)
end

#get_room_topic(room_id, **params) ⇒ Object 



507
508
509
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 507

def get_room_topic(room_id, **params)
  get_room_state(room_id, 'm.room.topic', params)
end

#get_user_tags(user_id, room_id, **params) ⇒ Object 



617
618
619
620
621
622
623
624
625
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 617

def get_user_tags(user_id, room_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s
  user_id = ERB::Util.url_encode user_id.to_s

  request(:get, :client_r0, "/user/#{user_id}/rooms/#{room_id}/tags", query: query)
end

#invite_user(room_id, user_id, **params) ⇒ Object 



545
546
547
548
549
550
551
552
553
554
555
556
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 545

def invite_user(room_id, user_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    user_id: user_id
  }

  room_id = ERB::Util.url_encode room_id.to_s

  request(:post, :client_r0, "/rooms/#{room_id}/invite", body: content, query: query)
end

#join_room(id_or_alias, **params) ⇒ Response

TODO:

Add support for 3rd-party signed objects

Joins a room

Parameters:

  • id_or_alias (MXID, String) —

    The room ID or Alias to join

  • params (Hash) —

    Extra room join options

Options Hash (**params):

  • :server_name (String[]) —

    A list of servers to perform the join through

Returns:

  • (Response) —

    A response hash with the parameter :room_id

See Also:



228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 228

def join_room(id_or_alias, **params)
  query = {}
  query[:server_name] = params[:server_name] if params[:server_name]
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  # id_or_alias = MXID.new id_or_alias.to_s unless id_or_alias.is_a? MXID
  # raise ArgumentError, 'Not a room ID or alias' unless id_or_alias.room?

  id_or_alias = ERB::Util.url_encode id_or_alias.to_s

  request(:post, :client_r0, "/join/#{id_or_alias}", query: query)
end

#keys_query(timeout: nil, device_keys:, token: nil, **params) ⇒ Object 



865
866
867
868
869
870
871
872
873
874
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 865

def keys_query(timeout: nil, device_keys:, token: nil, **params)
  body = {
    timeout: (timeout || 10) * 1000,
    device_keys: device_keys
  }
  body[:timeout] = params[:timeout_ms] if params.key? :timeout_ms
  body[:token] = token if token

  request(:post, :client_r0, '/keys/query', body: body)
end

#kick_user(room_id, user_id, reason: '', **params) ⇒ Object 



558
559
560
561
562
563
564
565
566
567
568
569
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 558

def kick_user(room_id, user_id, reason: '', **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    user_id: user_id,
    reason: reason
  }
  room_id = ERB::Util.url_encode room_id.to_s

  request(:post, :client_r0, "/rooms/#{room_id}/kick", body: content, query: query)
end

#leave_room(room_id, **params) ⇒ Object 



527
528
529
530
531
532
533
534
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 527

def leave_room(room_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s

  request(:post, :client_r0, "/rooms/#{room_id}/leave", query: query)
end

#login(login_type: 'm.login.password', **params) ⇒ Response

Logs in using the client API /login endpoint, and optionally stores the resulting access for API usage

Examples:

Logging in with username and password

api.(user: 'example', password: 'NotARealPass')
# => { user_id: '@example:matrix.org', access_token: '...', home_server: 'matrix.org', device_id: 'ABCD123' }
api.whoami?
# => { user_id: '@example:matrix.org' }

Advanced login, without storing details

api.whoami?
# => { user_id: '@example:matrix.org' }
api.(medium: 'email', address: '[email protected]', password: '...', store_token: false)
# => { user_id: '@someone:matrix.org', access_token: ...
api.whoami?.user_id
# => '@example:matrix.org'

Parameters:

  • login_type (String) (defaults to: 'm.login.password') —

    (‘m.login.password’) The type of login to attempt

  • params (Hash) —

    The login information to use, along with options for said log in

Options Hash (**params):

  • :store_token (Boolean) — default: true —

    Should the resulting access token be stored for the API

  • :store_device_id (Boolean) — default: store_token value —

    Should the resulting device ID be stored for the API

  • :initial_device_display_name (String) — default: USER_AGENT —

    The device display name to specify for this login attempt

  • :device_id (String) —

    The device ID to set on the login

Returns:

  • (Response) —

    A response hash with the parameters :user_id, :access_token, :home_server, and :device_id.

See Also:



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 123

def (login_type: 'm.login.password', **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  options = {}
  options[:store_token] = params.delete(:store_token) { true }
  options[:store_device_id] = params.delete(:store_device_id) { options[:store_token] }

  data = {
    type: ,
    initial_device_display_name: params.delete(:initial_device_display_name) { MatrixSdk::Api::USER_AGENT }
  }.merge params
  data[:device_id] = device_id if device_id

  request(:post, :client_r0, '/login', body: data, query: query).tap do |resp|
    @access_token = resp.token if resp.key?(:token) && options[:store_token]
    @device_id = resp.device_id if resp.key?(:device_id) && options[:store_device_id]
  end
end

#logout(**params) ⇒ Response

Logs out the currently logged in user

Returns:

  • (Response) —

    An empty response if the logout was successful

See Also:



147
148
149
150
151
152
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 147

def logout(**params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  request(:post, :client_r0, '/logout', query: query)
end

#media_upload(content, content_type, **params) ⇒ Object 



717
718
719
720
721
722
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 717

def media_upload(content, content_type, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  request(:post, :media_r0, '/upload', body: content, headers: { 'content-type' => content_type }, query: query)
end

#redact_event(room_id, event_id, **params) ⇒ Response

Redact an event in a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the message event to

  • event_id (String) —

    The event ID of the event to redact

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :reason (String) —

    The reason for the redaction

  • :txn_id (Integer) —

    The ID of the transaction, or automatically generated

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 294

def redact_event(room_id, event_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {}
  content[:reason] = params[:reason] if params[:reason]

  txn_id = transaction_id
  txn_id = params.fetch(:txn_id, "#{txn_id}#{Time.now.to_i}")

  room_id = ERB::Util.url_encode room_id.to_s
  event_id = ERB::Util.url_encode event_id.to_s
  txn_id = ERB::Util.url_encode txn_id.to_s

  request(:put, :client_r0, "/rooms/#{room_id}/redact/#{event_id}/#{txn_id}", body: content, query: query)
end

#register(kind: 'user', **params) ⇒ Response

Registers a user using the client API /register endpoint

Examples:

Regular user registration and login

api.register(username: 'example', password: 'NotARealPass')
# => { user_id: '@example:matrix.org', access_token: '...', home_server: 'matrix.org', device_id: 'ABCD123' }
api.whoami?
# => { user_id: '@example:matrix.org' }

Parameters:

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

    (‘user’) The kind of registration to use

  • params (Hash) —

    The registration information, all not handled by Ruby will be passed as JSON in the body

Options Hash (**params):

  • :store_token (Boolean) — default: true —

    Should the resulting access token be stored for the API

  • :store_device_id (Boolean) — default: store_token value —

    Should the resulting device ID be stored for the API

Returns:

See Also:



71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 71

def register(kind: 'user', **params)
  query = {}
  query[:kind] = kind
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  store_token = params.delete(:store_token) { !protocol?(:AS) }
  store_device_id = params.delete(:store_device_id) { store_token }

  request(:post, :client_r0, '/register', body: params, query: query).tap do |resp|
    @access_token = resp.token if resp.key?(:token) && store_token
    @device_id = resp.device_id if resp.key?(:device_id) && store_device_id
  end
end

#remove_room_alias(room_alias, **params) ⇒ Object 



808
809
810
811
812
813
814
815
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 808

def remove_room_alias(room_alias, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_alias = ERB::Util.url_encode room_alias.to_s

  request(:delete, :client_r0, "/directory/room/#{room_alias}", query: query)
end

#remove_user_tag(user_id, room_id, tag, **params) ⇒ Object 



627
628
629
630
631
632
633
634
635
636
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 627

def remove_user_tag(user_id, room_id, tag, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s
  user_id = ERB::Util.url_encode user_id.to_s
  tag = ERB::Util.url_encode tag.to_s

  request(:delete, :client_r0, "/user/#{user_id}/rooms/#{room_id}/tags/#{tag}", query: query)
end

#send_content(room_id, url, name, msg_type, **params) ⇒ Response

Send a content message to a room

Examples:

Sending an image to a room

send_content('!abcd123:localhost',
             'mxc://localhost/1234567',
             'An image of a cat',
             'm.image',
             extra_information: {
               h: 128,
               w: 128,
               mimetype: 'image/png',
               size: 1024
             })

Sending a file to a room

send_content('!example:localhost',
             'mxc://localhost/fileurl',
             'Contract.pdf',
             'm.file',
             extra_content: {
               filename: 'contract.pdf'
             },
             extra_information: {
               mimetype: 'application/pdf',
               size: 96674
             })

Parameters:

  • room_id (MXID, String) —

    The room ID to send the content to

  • url (URI, String) —

    The URL to the content

  • name (String) —

    The name of the content

  • msg_type (String) —

    The message type of the content

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :extra_information (Hash) — default: {} —

    Extra information for the content

  • :extra_content (Hash) —

    Extra data to insert into the content hash

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



352
353
354
355
356
357
358
359
360
361
362
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 352

def send_content(room_id, url, name, msg_type, **params)
  content = {
    url: url,
    msgtype: msg_type,
    body: name,
    info: params.delete(:extra_information) { {} }
  }
  content.merge!(params.fetch(:extra_content)) if params.key? :extra_content

  send_message_event(room_id, 'm.room.message', content, params)
end

#send_emote(room_id, emote, **params) ⇒ Response

Send a plaintext emote to a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the message to

  • emote (String) —

    The emote to send

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :msg_type (String) — default: 'm.emote' —

    The message type to send

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



418
419
420
421
422
423
424
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 418

def send_emote(room_id, emote, **params)
  content = {
    msgtype: params.delete(:msg_type) { 'm.emote' },
    body: emote
  }
  send_message_event(room_id, 'm.room.message', content, params)
end

#send_location(room_id, geo_uri, name, **params) ⇒ Response

Send a geographic location to a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the location to

  • geo_uri (URI, String) —

    The geographical URI to send

  • name (String) —

    The name of the location

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :extra_information (Hash) — default: {} —

    Extra information for the location

  • :thumbnail_url (URI, String) —

    The URL to a thumbnail of the location

  • :thumbnail_info (Hash) —

    Image information about the location thumbnail

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



377
378
379
380
381
382
383
384
385
386
387
388
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 377

def send_location(room_id, geo_uri, name, **params)
  content = {
    geo_uri: geo_uri,
    msgtype: 'm.location',
    body: name,
    info: params.delete(:extra_information) { {} }
  }
  content[:info][:thumbnail_url] = params.delete(:thumbnail_url) if params.key? :thumbnail_url
  content[:info][:thumbnail_info] = params.delete(:thumbnail_info) if params.key? :thumbnail_info

  send_message_event(room_id, 'm.room.message', content, params)
end

#send_message(room_id, message, **params) ⇒ Response

Send a plaintext message to a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the message to

  • message (String) —

    The message to send

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :msg_type (String) — default: 'm.text' —

    The message type to send

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



400
401
402
403
404
405
406
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 400

def send_message(room_id, message, **params)
  content = {
    msgtype: params.delete(:msg_type) { 'm.text' },
    body: message
  }
  send_message_event(room_id, 'm.room.message', content, params)
end

#send_message_event(room_id, event_type, content, **params) ⇒ Response

Sends a message event to a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the message event to

  • event_type (String) —

    The event type of the message

  • content (Hash) —

    The contents of the message

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :txn_id (Integer) —

    The ID of the transaction, or automatically generated

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 271

def send_message_event(room_id, event_type, content, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  txn_id = transaction_id
  txn_id = params.fetch(:txn_id, "#{txn_id}#{Time.now.to_i}")

  room_id = ERB::Util.url_encode room_id.to_s
  event_type = ERB::Util.url_encode event_type.to_s
  txn_id = ERB::Util.url_encode txn_id.to_s

  request(:put, :client_r0, "/rooms/#{room_id}/send/#{event_type}/#{txn_id}", body: content, query: query)
end

#send_notice(room_id, notice, **params) ⇒ Response

Send a plaintext notice to a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the message to

  • notice (String) —

    The notice to send

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :msg_type (String) — default: 'm.notice' —

    The message type to send

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



436
437
438
439
440
441
442
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 436

def send_notice(room_id, notice, **params)
  content = {
    msgtype: params.delete(:msg_type) { 'm.notice' },
    body: notice
  }
  send_message_event(room_id, 'm.room.message', content, params)
end

#send_state_event(room_id, event_type, content, **params) ⇒ Response

Sends a state event to a room

Parameters:

  • room_id (MXID, String) —

    The room ID to send the state event to

  • event_type (String) —

    The event type to send

  • content (Hash) —

    The contents of the state event

  • params (Hash) —

    Options for the request

Options Hash (**params):

  • :state_key (String) —

    The state key of the event, if there is one

Returns:

  • (Response) —

    A response hash with the parameter :event_id

See Also:



251
252
253
254
255
256
257
258
259
260
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 251

def send_state_event(room_id, event_type, content, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  room_id = ERB::Util.url_encode room_id.to_s
  event_type = ERB::Util.url_encode event_type.to_s
  state_key = ERB::Util.url_encode params[:state_key].to_s if params.key? :state_key

  request(:put, :client_r0, "/rooms/#{room_id}/state/#{event_type}#{"/#{state_key}" unless state_key.nil?}", body: content, query: query)
end

#set_account_data(user_id, type_key, account_data, **params) ⇒ Object 



666
667
668
669
670
671
672
673
674
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 666

def (user_id, type_key, , **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s
  type_key = ERB::Util.url_encode type_key.to_s

  request(:put, :client_r0, "/user/#{user_id}/account_data/#{type_key}", body: , query: query)
end

#set_avatar_url(user_id, url, **params) ⇒ Object 



755
756
757
758
759
760
761
762
763
764
765
766
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 755

def set_avatar_url(user_id, url, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    avatar_url: url
  }

  user_id = ERB::Util.url_encode user_id.to_s

  request(:put, :client_r0, "/profile/#{user_id}/avatar_url", body: content, query: query)
end

#set_device(device_id, display_name:) ⇒ Object 



853
854
855
856
857
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 853

def set_device(device_id, display_name:)
  device_id = ERB::Util.url_encode device_id.to_s

  request(:put, :client_r0, "/devices/#{device_id}", body: { display_name: display_name })
end

#set_display_name(user_id, display_name, **params) ⇒ Object 



733
734
735
736
737
738
739
740
741
742
743
744
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 733

def set_display_name(user_id, display_name, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    displayname: display_name
  }

  user_id = ERB::Util.url_encode user_id.to_s

  request(:put, :client_r0, "/profile/#{user_id}/displayname", body: content, query: query)
end

#set_guest_access(room_id, guest_access, **params) ⇒ Object 



834
835
836
837
838
839
840
841
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 834

def set_guest_access(room_id, guest_access, **params)
  # raise ArgumentError, '`guest_access` must be one of [:can_join, :forbidden]' unless %i[can_join forbidden].include? guest_access
  content = {
    guest_access: guest_access
  }

  send_state_event(room_id, 'm.room.guest_access', params.merge(content))
end

#set_join_rule(room_id, join_rule, **params) ⇒ Object 



826
827
828
829
830
831
832
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 826

def set_join_rule(room_id, join_rule, **params)
  content = {
    join_rule: join_rule
  }

  send_state_event(room_id, 'm.room.join_rules', params.merge(content))
end

#set_membership(room_id, user_id, membership, reason: '', **params) ⇒ Object 



581
582
583
584
585
586
587
588
589
590
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 581

def set_membership(room_id, user_id, membership, reason: '', **params)
  content = {
    membership: membership,
    reason: reason
  }
  content[:displayname] = params.delete(:displayname) if params.key? :displayname
  content[:avatar_url] = params.delete(:avatar_url) if params.key? :avatar_url

  send_state_event(room_id, 'm.room.member', content, params.merge(state_key: user_id))
end

#set_power_levels(room_id, content, **params) ⇒ Object 



522
523
524
525
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 522

def set_power_levels(room_id, content, **params)
  content[:events] = {} unless content.key? :events
  send_state_event(room_id, 'm.room.power_levels', content, params)
end

#set_room_account_data(user_id, room_id, type_key, account_data, **params) ⇒ Object 



687
688
689
690
691
692
693
694
695
696
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 687

def (user_id, room_id, type_key, , **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  user_id = ERB::Util.url_encode user_id.to_s
  room_id = ERB::Util.url_encode room_id.to_s
  type_key = ERB::Util.url_encode type_key.to_s

  request(:put, :client_r0, "/user/#{user_id}/rooms/#{room_id}/account_data/#{type_key}", body: , query: query)
end

#set_room_alias(room_id, room_alias, **params) ⇒ Object 



796
797
798
799
800
801
802
803
804
805
806
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 796

def set_room_alias(room_id, room_alias, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    room_id: room_id
  }
  room_alias = ERB::Util.url_encode room_alias.to_s

  request(:put, :client_r0, "/directory/room/#{room_alias}", body: content, query: query)
end

#set_room_name(room_id, name, **params) ⇒ Object 



500
501
502
503
504
505
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 500

def set_room_name(room_id, name, **params)
  content = {
    name: name
  }
  send_state_event(room_id, 'm.room.name', content, params)
end

#set_room_topic(room_id, topic, **params) ⇒ Object 



511
512
513
514
515
516
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 511

def set_room_topic(room_id, topic, **params)
  content = {
    topic: topic
  }
  send_state_event(room_id, 'm.room.topic', content, params)
end

#sync(timeout: 30.0, **params) ⇒ Response

Runs the client API /sync method

Parameters:

  • timeout (Numeric) (defaults to: 30.0) —

    (30.0) The timeout in seconds for the sync

  • params (Hash) —

    The sync options to use

Options Hash (**params):

  • :since (String) —

    The value of the batch token to base the sync from

  • :filter (String, Hash) —

    The filter to use on the sync

  • :full_state (Boolean) —

    Should the sync include the full state

  • :set_presence (Boolean) —

    Should the sync set the user status to online

Returns:

See Also:



42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 42

def sync(timeout: 30.0, **params)
  query = {
    timeout: timeout
  }.merge(params).select do |k, _v|
    %i[since filter full_state set_presence].include? k
  end

  query[:timeout] = (query.fetch(:timeout, 30) * 1000).to_i
  query[:timeout] = params.delete(:timeout_ms).to_i if params.key? :timeout_ms
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  request(:get, :client_r0, '/sync', query: query)
end

#unban_user(room_id, user_id, **params) ⇒ Object 



605
606
607
608
609
610
611
612
613
614
615
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 605

def unban_user(room_id, user_id, **params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  content = {
    user_id: user_id
  }
  room_id = ERB::Util.url_encode room_id.to_s

  request(:post, :client_r0, "/rooms/#{room_id}/unban", body: content, query: query)
end

#username_available?(username) ⇒ Response

Checks if a given username is available and valid for registering

Examples:

Verifying a username

api.username_available?('example')
# => { available: true }

Parameters:

  • username (String) —

    The username to check

Returns:

See Also:



94
95
96
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 94

def username_available?(username)
  request(:get, :client_r0, '/register/available', query: { username: username })
end

#whoami?(**params) ⇒ Boolean

Returns:

  • (Boolean) 


876
877
878
879
880
881
 
# File 'lib/matrix_sdk/protocols/cs.rb', line 876

def whoami?(**params)
  query = {}
  query[:user_id] = params.delete(:user_id) if protocol?(:AS) && params.key?(:user_id)

  request(:get, :client_r0, '/account/whoami', query: query)
end