matrix_sdk 1.5.0 → 2.0.0

data/lib/matrix_sdk/response.rb

@@ -22,6 +22,17 @@ module MatrixSdk
   #   @return [Api] The API connection that returned the response
   module Response
     def self.new(api, data)
+      if data.is_a? Array
+        raise ArgumentError, 'Input data was not an array of hashes' unless data.all? { |v| v.is_a? Hash }
+
+        data.each do |value|
+          Response.new api, value
+        end
+        return data
+      end
+
+      raise ArgumentError, 'Input data was not a hash' unless data.is_a? Hash
+
       data.extend(Extensions)
       data.instance_variable_set(:@api, api)
 

data/lib/matrix_sdk/room.rb

@@ -58,10 +58,34 @@ module MatrixSdk
 
     alias room_id id
 
+    # Create a new room instance
+    #
+    # @note This method isn't supposed to be used directly, rather rooms should
+    #       be retrieved from the Client abstraction.
+    #
+    # @param client [Client] The underlying connection
+    # @param room_id [MXID] The room ID
+    # @param data [Hash] Additional data to assign to the room
+    # @option data [String] :name The current name of the room
+    # @option data [String] :topic The current topic of the room
+    # @option data [String,MXID] :canonical_alias The canonical alias of the room
+    # @option data [Array(String,MXID)] :aliases All non-canonical aliases of the room
+    # @option data [:invite,:public] :join_rule The join rule for the room
+    # @option data [:can_join,:forbidden] :guest_access The guest access setting for the room
+    # @option data [Boolean] :world_readable If the room is readable by the entire world
+    # @option data [Array(User)] :members The list of joined members
+    # @option data [Array(Object)] :events The list of current events in the room
+    # @option data [Boolean] :members_loaded If the list of members is already loaded
+    # @option data [Integer] :event_history_limit (10) The limit of events to store for the room
+    # @option data [String,URI] :avatar_url The avatar URL for the room
+    # @option data [String] :prev_batch The previous batch token for backfill
     def initialize(client, room_id, data = {})
+      raise ArgumentError, 'Must be given a Client instance' unless client.is_a? Client
+
+      room_id = MXID.new room_id unless room_id.is_a?(MXID)
+      raise ArgumentError, 'room_id must be a valid Room ID' unless room_id.room_id?
+
       event_initialize
-      @client = client
-      @id = room_id.to_s
 
       @name = nil
       @topic = nil
@@ -82,6 +106,9 @@ module MatrixSdk
         instance_variable_set("@#{k}", v) if instance_variable_defined? "@#{k}"
       end
 
+      @client = client
+      @id = room_id.to_s
+
       @name_checked = Time.new(0)
 
       logger.debug "Created room #{room_id}"
@@ -116,20 +143,27 @@ module MatrixSdk
     end
 
     # Populates and returns the #members array
+    #
+    # @return [Array(User)] The list of members in the room
     def joined_members
       return members if @members_loaded && !members.empty?
 
-      client.api.get_room_members(id)[:chunk].each do |chunk|
-        next unless chunk [:content][:membership] == 'join'
-
-        ensure_member(User.new(client, chunk[:state_key], display_name: chunk[:content].fetch(:displayname, nil)))
+      client.api.get_room_joined_members(id)[:joined].each do |mxid, data|
+        ensure_member(User.new(client, mxid.to_s,
+                               display_name: data.fetch(:display_name, nil),
+                               avatar_url: data.fetch(:avatar_url, nil)))
       end
       @members_loaded = true
       members
     end
 
+    # Gets the current name of the room, querying the API if necessary
+    #
+    # @note Will cache the current name for 15 minutes
+    #
+    # @return [String,nil] The room name - if any
     def name
-      return @name if Time.now - @name_checked < 10
+      return @name if Time.now - @name_checked < 900
 
       @name_checked = Time.now
       @name ||= client.api.get_room_name(id)
@@ -139,6 +173,8 @@ module MatrixSdk
     end
 
     # Gets the avatar url of the room - if any
+    #
+    # @return [String,nil] The avatar URL - if any
     def avatar_url
       @avatar_url ||= client.api.get_room_avatar(id).url
     rescue MatrixNotFoundError
@@ -169,23 +205,26 @@ module MatrixSdk
     #
 
     # Sends a plain-text message to the room
+    #
     # @param text [String] the message to send
     def send_text(text)
       client.api.send_message(id, text)
     end
 
     # Sends a custom HTML message to the room
+    #
     # @param html [String] the HTML message to send
     # @param body [String,nil] a plain-text representation of the object
-    #        (Will default to the HTML with tags stripped away)
-    # @param msg_type [String] A message type for the message
+    #        (Will default to the HTML with all tags stripped away)
+    # @param msgtype [String] ('m.text') The message type for the message
+    # @param format [String] ('org.matrix.custom.html') The message format
     # @see https://matrix.org/docs/spec/client_server/r0.3.0.html#m-room-message-msgtypes
     #      Possible message types as defined by the spec
-    def send_html(html, body = nil, msg_type = 'm.text')
+    def send_html(html, body = nil, msgtype: nil, format: nil)
       content = {
         body: body || html.gsub(/<\/?[^>]*>/, ''),
-        msgtype: msg_type,
-        format: 'org.matrix.custom.html',
+        msgtype: msgtype || 'm.text',
+        format: format || 'org.matrix.custom.html',
         formatted_body: html
       }
 
@@ -193,12 +232,14 @@ module MatrixSdk
     end
 
     # Sends an emote (/me) message to the room
+    #
     # @param text [String] the emote to send
     def send_emote(text)
       client.api.send_emote(id, text)
     end
 
     # Sends a link to a generic file to the room
+    #
     # @param url [String,URI] the URL to the file
     # @param name [String] the name of the file
     # @param file_info [Hash] extra information about the file
@@ -212,12 +253,14 @@ module MatrixSdk
     end
 
     # Sends a notice (bot) message to the room
+    #
     # @param text [String] the notice to send
     def send_notice(text)
       client.api.send_notice(id, text)
     end
 
     # Sends a link to an image to the room
+    #
     # @param url [String,URI] the URL to the image
     # @param name [String] the name of the image
     # @param image_info [Hash] extra information about the image
@@ -233,6 +276,7 @@ module MatrixSdk
     end
 
     # Sends a location object to the room
+    #
     # @param geo_uri [String,URI] the geo-URL (e.g. geo:<coords>) of the location
     # @param name [String] the name of the location
     # @param thumbnail_url [String,URI] the URL to a thumbnail image of the location
@@ -243,6 +287,7 @@ module MatrixSdk
     end
 
     # Sends a link to a video to the room
+    #
     # @param url [String,URI] the URL to the video
     # @param name [String] the name of the video
     # @param video_info [Hash] extra information about the video
@@ -259,6 +304,7 @@ module MatrixSdk
     end
 
     # Sends a link to an audio clip to the room
+    #
     # @param url [String,URI] the URL to the audio clip
     # @param name [String] the name of the audio clip
     # @param audio_info [Hash] extra information about the audio clip
@@ -271,6 +317,7 @@ module MatrixSdk
     end
 
     # Redacts a message from the room
+    #
     # @param event_id [String] the ID of the event to redact
     # @param reason [String,nil] the reason for the redaction
     def redact_message(event_id, reason = nil)
@@ -278,7 +325,18 @@ module MatrixSdk
       true
     end
 
+    # Reports a message in the room
+    #
+    # @param event_id [MXID,String] The ID of the event to redact
+    # @param reason [String] The reason for the report
+    # @param score [Integer] The severity of the report in the range of -100 - 0
+    def report_message(event_id, reason:, score: -100)
+      client.api.report_event(id, event_id, reason: reason, score: score)
+      true
+    end
+
     # Backfills messages into the room history
+    #
     # @param reverse [Boolean] whether to fill messages in reverse or not
     # @param limit [Integer] the maximum number of messages to backfill
     # @note This will trigger the `on_event` events as messages are added
@@ -298,6 +356,7 @@ module MatrixSdk
     #
 
     # Invites a user into the room
+    #
     # @param user_id [String,User] the MXID of the user
     # @return [Boolean] wether the action succeeded
     def invite_user(user_id)
@@ -307,6 +366,7 @@ module MatrixSdk
     end
 
     # Kicks a user from the room
+    #
     # @param user_id [String,User] the MXID of the user
     # @param reason [String] the reason for the kick
     # @return [Boolean] wether the action succeeded
@@ -317,6 +377,7 @@ module MatrixSdk
     end
 
     # Bans a user from the room
+    #
     # @param user_id [String,User] the MXID of the user
     # @param reason [String] the reason for the ban
     # @return [Boolean] wether the action succeeded
@@ -327,6 +388,7 @@ module MatrixSdk
     end
 
     # Unbans a user from the room
+    #
     # @param user_id [String,User] the MXID of the user
     # @return [Boolean] wether the action succeeded
     def unban_user(user_id)
@@ -336,6 +398,7 @@ module MatrixSdk
     end
 
     # Requests to be removed from the room
+    #
     # @return [Boolean] wether the request succeeded
     def leave
       client.api.leave_room(id)
@@ -344,6 +407,7 @@ module MatrixSdk
     end
 
     # Retrieves a custom entry from the room-specific account data
+    #
     # @param type [String] the data type to retrieve
     # @return [Hash] the data that was stored under the given type
     def get_account_data(type)
@@ -351,6 +415,7 @@ module MatrixSdk
     end
 
     # Stores a custom entry into the room-specific account data
+    #
     # @param type [String] the data type to store
     # @param account_data [Hash] the data to store
     def set_account_data(type, account_data)
@@ -359,6 +424,7 @@ module MatrixSdk
     end
 
     # Changes the room-specific user profile
+    #
     # @param display_name [String] the new display name to use in the room
     # @param avatar_url [String,URI] the new avatar URL to use in the room
     # @note the avatar URL should be a mxc:// URI
@@ -376,6 +442,7 @@ module MatrixSdk
     end
 
     # Returns a list of the room tags
+    #
     # @return [Response] A list of the tags and their data, with add and remove methods implemented
     # @example Managing tags
     #   room.tags
@@ -403,6 +470,7 @@ module MatrixSdk
     end
 
     # Remove a tag from the room
+    #
     # @param [String] tag The tag to remove
     def remove_tag(tag)
       client.api.remove_user_tag(client.mxid, id, tag)
@@ -410,6 +478,7 @@ module MatrixSdk
     end
 
     # Add a tag to the room
+    #
     # @param [String] tag The tag to add
     # @param [Hash] data The data to assign to the tag
     def add_tag(tag, **data)
@@ -421,6 +490,7 @@ module MatrixSdk
     # State updates
     #
 
+    # Refreshes the room state caches for name, topic, and aliases
     def reload!
       reload_name!
       reload_topic!
@@ -429,12 +499,16 @@ module MatrixSdk
     end
     alias refresh! reload!
 
+    # Sets a new name on the room
+    #
+    # @param name [String] The new name to set
     def name=(name)
       client.api.set_room_name(id, name)
       @name = name
     end
 
     # Reloads the name of the room
+    #
     # @return [Boolean] if the name was changed or not
     def reload_name!
       data = begin
@@ -448,12 +522,16 @@ module MatrixSdk
     end
     alias refresh_name! reload_name!
 
+    # Sets a new topic on the room
+    #
+    # @param topic [String] The new topic to set
     def topic=(topic)
       client.api.set_room_topic(id, topic)
       @topic = topic
     end
 
     # Reloads the topic of the room
+    #
     # @return [Boolean] if the topic was changed or not
     def reload_topic!
       data = begin
@@ -468,6 +546,7 @@ module MatrixSdk
     alias refresh_topic! reload_topic!
 
     # Add an alias to the room
+    #
     # @return [Boolean] if the addition was successful or not
     def add_alias(room_alias)
       client.api.set_room_alias(id, room_alias)
@@ -476,6 +555,7 @@ module MatrixSdk
     end
 
     # Reloads the list of aliases by an API query
+    #
     # @return [Boolean] if the alias list was updated or not
     # @note The list of aliases is not sorted, ordering changes will result in
     #       alias list updates.
@@ -483,7 +563,7 @@ module MatrixSdk
       begin
         new_aliases = client.api.get_room_aliases(id).aliases
       rescue MatrixNotFoundError
-        data = client.api.get_room_state(id)
+        data = client.api.get_room_state_all(id)
         new_aliases = data.select { |chunk| chunk[:type] == 'm.room.aliases' && chunk.key?(:content) && chunk[:content].key?(:aliases) }
                           .map { |chunk| chunk[:content][:aliases] }
                           .flatten
@@ -498,26 +578,41 @@ module MatrixSdk
     end
     alias refresh_aliases! reload_aliases!
 
+    # Sets if the room should be invite only or not
+    #
+    # @param invite_only [Boolean] If it should be invite only or not
     def invite_only=(invite_only)
       self.join_rule = invite_only ? :invite : :public
       @join_rule == :invite
     end
 
+    # Sets the join rule of the room
+    #
+    # @param join_rule [:invite,:public] The join rule of the room
     def join_rule=(join_rule)
       client.api.set_join_rule(id, join_rule)
       @join_rule = join_rule
     end
 
+    # Sets if guests are allowed in the room
+    #
+    # @param allow_guests [Boolean] If guests are allowed to join or not
     def allow_guests=(allow_guests)
       self.guest_access = (allow_guests ? :can_join : :forbidden)
       @guest_access == :can_join
     end
 
+    # Sets the guest access status for the room
+    #
+    # @param guest_access [:can_join,:forbidden] The new guest access status of the room
     def guest_access=(guest_access)
       client.api.set_guest_access(id, guest_access)
       @guest_access = guest_access
     end
 
+    # Sets a new avatar URL for the room
+    #
+    # @param avatar_url [URI::MATRIX] The mxc:// URL for the new room avatar
     def avatar_url=(avatar_url)
       avatar_url = URI(avatar_url) unless avatar_url.is_a? URI
       raise ArgumentError, 'Must be a valid MXC URL' unless avatar_url.is_a? URI::MATRIX
@@ -527,6 +622,7 @@ module MatrixSdk
     end
 
     # Modifies the power levels of the room
+    #
     # @param users [Hash] the user-specific power levels to set or remove
     # @param users_default [Hash] the default user power levels to set
     # @return [Boolean] if the change was successful
@@ -547,6 +643,7 @@ module MatrixSdk
     end
 
     # Modifies the required power levels for actions in the room
+    #
     # @param events [Hash] the event-specific power levels to change
     # @param params [Hash] other power-level params to change
     # @return [Boolean] if the change was successful

data/lib/matrix_sdk/user.rb

@@ -7,10 +7,6 @@ module MatrixSdk
   class User
     extend MatrixSdk::Extensions
 
-    # @!attribute [r] id
-    #   @return [String] the MXID of the user
-    # @!attribute [r] client
-    #   @return [Client] the client for the user
     attr_reader :id, :client
     alias user_id :id
 
@@ -32,14 +28,14 @@ module MatrixSdk
       end
     end
 
-    # @!attribute [r] display_name
     # @return [String] the display name
+    # @see MatrixSdk::Protocols::CS#get_display_name
     def display_name
       @display_name ||= client.api.get_display_name(id)[:displayname]
     end
 
-    # @!attribute [w] display_name
     # @param name [String] the display name to set
+    # @see MatrixSdk::Protocols::CS#set_display_name
     def display_name=(name)
       client.api.set_display_name(id, name)
       @display_name = name
@@ -51,21 +47,92 @@ module MatrixSdk
       display_name || id
     end
 
-    # @!attribute [r] avatar_url
+    # Gets the avatar for the user
+    #
+    # @see MatrixSdk::Protocols::CS#get_avatar_url
     def avatar_url
       @avatar_url ||= client.api.get_avatar_url(id)[:avatar_url]
     end
 
-    # @!attribute [w] avatar_url
+    # Set a new avatar for the user
+    #
+    # Only works for the current user object, as requested by
+    #     client.get_user(:self)
+    #
+    # @param url [String,URI::MATRIX] the new avatar URL
+    # @note Requires a mxc:// URL, check example on
+    #   {MatrixSdk::Protocols::CS#set_avatar_url} for how this can be done
+    # @see MatrixSdk::Protocols::CS#set_avatar_url
     def avatar_url=(url)
       client.api.set_avatar_url(id, url)
       @avatar_url = url
     end
 
+    # Get the user's current presence status
+    #
+    # @return [Symbol] One of :online, :offline, :unavailable
+    # @see MatrixSdk::Protocols::CS#get_presence_status
+    # @note This information is not cached in the abstraction layer
+    def presence
+      raw_presence[:presence].to_sym
+    end
+
+    # Sets the user's current presence status
+    # Should be one of :online, :offline, or :unavailable
+    #
+    # @param new_presence [:online,:offline,:unavailable] The new presence status to set
+    # @see MatrixSdk::Protocols::CS#set_presence_status
+    def presence=(new_presence)
+      raise ArgumentError, 'Presence must be one of :online, :offline, :unavailable' unless %i[online offline unavailable].include?(presence)
+
+      client.api.set_presence_status(id, new_presence)
+    end
+
+    # @return [Boolean] if the user is currently active
+    # @note This information is not cached in the abstraction layer
+    def active?
+      raw_presence[:currently_active] == true
+    end
+
+    # Gets the user-specified status message - if any
+    #
+    # @see MatrixSdk::Protocols::CS#get_presence_status
+    # @note This information is not cached in the abstraction layer
+    def status_msg
+      raw_presence[:status_msg]
+    end
+
+    # Sets the user-specified status message
+    #
+    # @param message [String,nil] The message to set, or nil for no message
+    # @see MatrixSdk::Protocols::CS#set_presence_status
+    def status_msg=(message)
+      client.api.set_presence_status(id, presence, message: message)
+    end
+
+    # Gets the last time the user was active at, from the server's side
+    #
+    # @return [Time] when the user was last active
+    # @see MatrixSdk::Protocols::CS#get_presence_status
+    # @note This information is not cached in the abstraction layer
+    def last_active
+      since = raw_presence[:last_active_ago]
+      return unless since
+
+      Time.now - (since / 1000)
+    end
+
+    # Returns all the current device keys for the user, retrieving them if necessary
     def device_keys
       @device_keys ||= client.api.keys_query(device_keys: { id => [] }).yield_self do |resp|
         resp[:device_keys][id.to_sym]
       end
     end
+
+    private
+
+    def raw_presence
+      client.api.get_presence_status(id).tap { |h| h.delete :user_id }
+    end
   end
 end