chatrix 1.0.0.pre → 1.0.0

data/lib/chatrix/api/rooms.rb

@@ -0,0 +1,213 @@
+require 'chatrix/api/api_component'
+require 'chatrix/api/room_actions'
+
+module Chatrix
+  module Api
+    # Contains methods for using room endpoints in the API.
+    class Rooms < ApiComponent
+      # @return [RoomActions] an instance of RoomActions to perform
+      #   room actions such as joining a room or sending messages.
+      attr_reader :actions
+
+      # Initializes a new Rooms instance.
+      # @param matrix [Matrix] The matrix API instance.
+      def initialize(matrix)
+        super
+        @actions = Api::RoomActions.new @matrix
+      end
+
+      # Get the list of public rooms on the server.
+      #
+      # The `start` and `end` values returned in the result can be passed to
+      # `from` and `to`, for pagination purposes.
+      #
+      # @param from [String] The stream token to start looking from.
+      # @param to [String] The stream token to stop looking at.
+      # @param limit [Fixnum] Maximum number of results to
+      #   return in one request.
+      # @param direction ['f', 'b'] Direction to look in.
+      # @return [Hash] Hash containing the list of rooms (in the `chunk` value),
+      #   and pagination parameters `start` and `end`.
+      def get_rooms(from: 'START', to: 'END', limit: 10, direction: 'b')
+        make_request(
+          :get,
+          '/publicRooms',
+          params: { from: from, to: to, limit: limit, dir: direction }
+        ).parsed_response
+      end
+
+      # Get tags that a specific user has set on a room.
+      #
+      # @param user [String] The user whose settings to retrieve
+      #   (`@user:host.tld`).
+      # @param room [String] The room to get tags from.
+      # @return [Hash{String=>Hash}] A hash with tag data. The tag name is
+      #   the key and any additional metadata is contained in the Hash value.
+      def get_user_tags(user, room)
+        make_request(:get, "/user/#{user}/rooms/#{room}/tags")['tags']
+      end
+
+      # Deletes a user tag from a room.
+      #
+      # @param user [String] The user to remove the tag for.
+      # @param room [String] The room to remove the tag from.
+      # @param tag [String] The tag to remove.
+      # @return [Boolean] `true` if the tag was removed successfully,
+      #   otherwise `false`.
+      def delete_user_tag(user, room, tag)
+        make_request(
+          :delete,
+          "/user/#{user}/rooms/#{room}/tags/#{tag}"
+        ).code == 200
+      end
+
+      # Adds a user tag to a room.
+      #
+      # @param user [String] The user adding the tag.
+      # @param room [String] The room to add the tag to.
+      # @param tag [String] The tag to add.
+      # @param data [Hash] Any additional data to add to the tag, e.g. ordering.
+      # @return [Boolean] `true` if the tag was successfully added,
+      #   otherwise `false`.
+      def add_user_tag(user, room, tag, data = {})
+        make_request(
+          :put,
+          "/user/#{user}/rooms/#{room}/tags/#{tag}",
+          content: data
+        ).code == 200
+      end
+
+      # Get information about a room alias.
+      #
+      # This can be used to get the room ID that an alias points to.
+      #
+      # @param room_alias [String] The room alias to query, this **must** be an
+      #   alias and not an ID.
+      # @return [Hash] Returns information about the alias in a Hash.
+      #
+      # @see #get_id #get_id is an example of how this method could be
+      #   used to get a room's ID.
+      def get_alias_info(room_alias)
+        make_request(:get, "/directory/room/#{room_alias}").parsed_response
+      rescue NotFoundError
+        raise RoomNotFoundError.new(room_alias),
+              'The specified room alias could not be found'
+      end
+
+      # Deletes a room alias.
+      # @param room_alias [String] The alias to delete.
+      # @return [Boolean] `true` if the alias was successfully removed,
+      #   otherwise `false`.
+      def delete_alias(room_alias)
+        make_request(:delete, "/directory/room/#{room_alias}").code == 200
+      end
+
+      # Creates a new alias for a room.
+      #
+      # @param room [String] The room to create an alias for.
+      # @param room_alias [String] The alias to create for the room.
+      # @return [Boolean] `true` if the alias was created successfully,
+      #   otherwise `false`.
+      def create_alias(room, room_alias)
+        make_request(
+          :put,
+          "/directory/room/#{room_alias}",
+          content: { room_id: room }
+        ).code == 200
+      end
+
+      # Get a room's ID from its alias.
+      #
+      # @param room_alias [String] The room alias to query.
+      # @return [String] The actual room ID for the room.
+      def get_id(room_alias)
+        get_room_alias_info(room_alias)['room_id']
+      end
+
+      # Gets context for an event in a room.
+      #
+      # The method will return events that happened before and after the
+      # specified event.
+      #
+      # @param room [String] The room to query.
+      # @param event [String] The event to get context for.
+      # @param limit [Fixnum] Maximum number of events to retrieve.
+      # @return [Hash] The returned hash contains information about the events
+      #   happening before and after the specified event, as well as start and
+      #   end timestamps and state information for the event.
+      def get_event_context(room, event, limit = 10)
+        make_request(
+          :get,
+          "/rooms/#{room}/context/#{event}",
+          params: { limit: limit }
+        ).parsed_response
+      end
+
+      # Get the members of a room.
+      #
+      # @param room [String] The room to query.
+      # @return [Array] An array of users that are in this room.
+      def get_members(room)
+        make_request(:get, "/rooms/#{room}/members")['chunk']
+      end
+
+      # Get a list of messages from a room.
+      #
+      # @param room [String] The room to get messages from.
+      # @param from [String] Token to return events from.
+      # @param direction ['b', 'f'] Direction to return events from.
+      # @param limit [Fixnum] Maximum number of events to return.
+      # @return [Hash] A hash containing the messages, as well as `start` and
+      #   `end` tokens for pagination.
+      def get_messages(room, from: 'START', to: 'END',
+                       direction: 'b', limit: 10)
+        make_request(
+          :get,
+          "/rooms/#{room}/messages",
+          params: { from: from, to: to, dir: direction, limit: limit }
+        ).parsed_response
+      end
+
+      # @overload get_room_state(room)
+      #   Get state events for the current state of a room.
+      #   @param room [String] The room to get events for.
+      #   @return [Array] An array with state events for the room.
+      # @overload get_room_state(room, type)
+      #   Get the contents of a specific kind of state in the room.
+      #   @param room [String] The room to get the data from.
+      #   @param type [String] The type of state to get.
+      #   @return [Hash] Information about the state type.
+      # @overload get_room_state(room, type, key)
+      #   Get the contents of a specific kind of state including only the
+      #   specified key in the result.
+      #   @param room [String] The room to get the data from.
+      #   @param type [String] The type of state to get.
+      #   @param key [String] The key of the state to look up.
+      #   @return [Hash] Information about the requested state.
+      def get_state(room, type = nil, key = nil)
+        if type && key
+          make_request(:get, "/rooms/#{room}/state/#{type}/#{key}")
+            .parsed_response
+        elsif type
+          make_request(:get, "/rooms/#{room}/state/#{type}").parsed_response
+        else
+          make_request(:get, "/rooms/#{room}/state").parsed_response
+        end
+      end
+
+      # Sends a state event to a room, with an optional state key.
+      # @param room [String] The room to send the event to.
+      # @param type [String] The event type to send.
+      # @param content [Hash] The content to set for the event.
+      # @param key [String,nil] Optional `state_key` to use.
+      # @return [String] The event ID for the sent event.
+      def send_state(room, type, content, key = nil)
+        path = "/rooms/#{room}/state/#{type}"
+
+        path += "/#{key}" if key
+
+        make_request(:put, path, content: content)['event_id']
+      end
+    end
+  end
+end

data/lib/chatrix/api/session.rb

@@ -0,0 +1,154 @@
+require 'chatrix/api/api_component'
+
+module Chatrix
+  module Api
+    # Contains methods to use session related endpoints in the API.
+    class Session < ApiComponent
+      # Gets third-party IDs associated with the current account.
+      # @return [Array] A list of 3rd party IDs.
+      def threepids
+        make_request(:get, '/account/3pid')['threepids']
+      end
+
+      # Adds third-party identification information to the user account.
+      # @param data [Hash] The data to add. Refer to the official documentation
+      #   for more information.
+      # @return [Boolean] `true` if the information was added successfully,
+      #   otherwise `false`.
+      def add_threepid(data)
+        make_request(:post, '/account/3pid', content: data).code == 200
+      end
+
+      # Set a new password for the current account.
+      #
+      # @note The server may request additional authentication as per the
+      #   official documentation on the "User-Interactive Authentication API".
+      #
+      # @param password [String] The new password to set.
+      # @param auth [Hash,nil] If provided, the hash will be passed in the
+      #   request as additional parameters inside the `auth` field.
+      # @return [Boolean] `true` if the password was successfully changed,
+      #   otherwise `false`.
+      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
+
+      # Registers a new user on the homeserver.
+      #
+      # @note On a successful registration, the
+      #   {Matrix#access_token access_token} and `refresh_token` will be
+      #   updated to the values returned by the server.
+      #
+      # @param 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.
+      #
+      # @param kind [String] The kind of registration to make.
+      #   Either `'guest'` or `'user'`.
+      #
+      # @return [Hash] On success, returns a hash with information about the
+      #   newly registered user. An example return value is given below.
+      #
+      #   ```ruby
+      #   {
+      #     'user_id' => '@foo:bar.org',
+      #     'home_server' => 'https://bar.org',
+      #     'access_token' => 'some secret token',
+      #     'refresh_token' => 'refresh token here'
+      #   }
+      #   ```
+      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
+
+      # Performs a login attempt.
+      #
+      # @note A successful login will update the
+      #   {Matrix#access_token access_token} to the new one returned from
+      #   the login response.
+      #
+      # @param method [String] The method to use for logging in.
+      #   For user/password combination, this should be `m.login.password`.
+      # @param 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.
+      # @return [Hash] The response from the server. A successful login will
+      #   return a hash containing the user id, access token, and homeserver.
+      #
+      # @example Logging in with username and password
+      #   login('m.login.password',
+      #         user: '@snoo:reddit.com', password: 'hunter2')
+      def login(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
+
+      # Logs out.
+      #
+      # @note This will **invalidate the access token**. It will no longer be
+      #   valid for further API calls.
+      #
+      # @return [Boolean] `true` if the user was successfully logged out,
+      #   otherwise `false`.
+      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
+
+      # Gets a new access token to use for API calls when the current one
+      # expires.
+      #
+      # @note On success, the internal {Matrix#access_token access_token} and
+      #   `refresh_token` will be updated automatically for use in
+      #   subsequent API calls.
+      #
+      # @param token [String,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.
+      # @return [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.
+      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
+    end
+  end
+end

data/lib/chatrix/api/users.rb

@@ -0,0 +1,176 @@
+require 'chatrix/api/api_component'
+
+module Chatrix
+  module Api
+    # Contains methods to use user endpoints in the API.
+    class Users < ApiComponent
+      # Gets information about a specific user.
+      #
+      # @param user [String] The user to query (`@user:host.tld`).
+      # @return [Hash] The user information.
+      # @raise [UserNotFoundError] If the user could not be found.
+      #
+      # @example Print a user's display name
+      #   puts get_user('@foo:matrix.org')['displayname']
+      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 the URL to a user's avatar (an `mxp://` URL).
+      #
+      # @param (see #get_user)
+      # @return [String] The avatar URL.
+      # @raise [AvatarNotFoundError] If the avatar or user could not be found.
+      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
+
+      # Sets a new avatar for a user.
+      #
+      # @param user [String] The user to update.
+      # @param avatar [String] The new avatar to set, an `mxc://` URL.
+      # @return [Boolean] `true` if the new avatar was set successfully,
+      #   otherwise `false`.
+      def set_avatar(user, avatar)
+        make_request(
+          :put,
+          "/profile/#{user}/avatar_url",
+          content: { avatar_url: avatar }
+        ).code == 200
+      end
+
+      # Get a user's display name (**not** username).
+      #
+      # @param (see #get_user)
+      # @raise (see #get_user)
+      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
+
+      # Sets a new display name for a user.
+      #
+      # @note Can only be used on the user who possesses the
+      #   {Matrix#access_token access_token} currently in use.
+      #
+      # @param user [String] The user to modify (`@user:host.tld`).
+      # @param displayname [String] The new displayname to set.
+      # @return [Boolean] `true` if the new display name was successfully set,
+      #   otherwise `false`.
+      def set_displayname(user, displayname)
+        make_request(
+          :put,
+          "/profile/#{user}/displayname",
+          content: { displayname: displayname }
+        ).code == 200
+      end
+
+      # Sets account data for a user.
+      #
+      # @param user [String] The user to add the data to.
+      # @param type [String] The event type of `account_data` to set.
+      # @param data [Hash] The actual data to set.
+      # @return [Boolean] `true` if the account data was successfully set,
+      #   otherwise `false`.
+      def set_data(user, type, data)
+        make_request(
+          :put,
+          "/user/#{user}/account_data/#{type}",
+          content: data
+        ).code == 200
+      end
+
+      # Sets account data for a user specific to a certain room.
+      #
+      # @param (see #set_data)
+      # @param room [String] The room to add the data in.
+      # @return [Boolean] `true` if the account data was successfully set
+      #   in the specified room, otherwise `false`.
+      def set_room_data(user, room, type, data)
+        make_request(
+          :put,
+          "/user/#{user}/rooms/#{room}/account_data/#{type}",
+          content: data
+        ).code == 200
+      end
+
+      # Gets the presence list for a user.
+      #
+      # @param user [String] The user whose list to get.
+      # @return [Array] A list of presences for this user.
+      #
+      # @todo The official documentation on this endpoint is weird, what does
+      #   this really do?
+      def get_presence_list(user)
+        make_request(:get, "/presence/list/#{user}").parsed_response
+      end
+
+      # Adds or removes users from a user's presence list.
+      #
+      # @param user [String] The user whose list to modify.
+      # @param data [Hash{String=>Array<String>}] Contains two arrays,
+      #   `invite` and `drop`. Users listed in the `invite` array will be
+      #   invited to join the presence list. Users listed in the `drop` array
+      #   will be removed from the presence list.
+      #   Note that both arrays are not required but at least one must be
+      #   present.
+      # @return [Boolean] `true` if the list was successfully updated,
+      #   otherwise `false`.
+      #
+      # @example Add and remove two users
+      #   update_presence_list(
+      #     '@me:home.org',
+      #     {
+      #       invite: ['@friend:home.org'],
+      #       drop: ['@enemy:other.org']
+      #     }
+      #   )
+      def update_presence_list(user, data)
+        make_request(
+          :post,
+          "/presence/list/#{user}",
+          content: { presence_diff: data }
+        ).code == 200
+      end
+
+      # Gets the presence status of a user.
+      #
+      # @param user [String] The user to query.
+      # @return [Hash] Hash with information about the user's presence,
+      #   contains information indicating if they are available and when
+      #   they were last active.
+      def get_presence_status(user)
+        make_request(:get, "/presence/#{user}/status").parsed_response
+      end
+
+      # Updates the presence status of a user.
+      #
+      # @note Only the user for whom the {Matrix#access_token access_token} is
+      #   valid for can have their presence updated.
+      #
+      # @param user [String] The user to update.
+      # @param status [String] The new status to set. Eg. `'online'`
+      #   or `'offline'`.
+      # @param message [String,nil] If set,
+      #   associates a message with the status.
+      # @return [Boolean] `true` if the presence was updated successfully,
+      #   otherwise `false`.
+      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
+    end
+  end
+end