chatrix 1.0.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f4d840405e59e950232bf4a82a906c7395d3c581
+  data.tar.gz: 26d630e954f5cc66b8bdd9dd5f01132ef6ca84af
+SHA512:
+  metadata.gz: bd3aa274eb0b3da53e24f8cfb95b354025513a421fd094172a912791de0962e171f9817906bb811bdc125047f415173c78a612ca7f9179bc1fc34ed710cf9e51
+  data.tar.gz: 61275fb3232b31c24b3e0d215107655ecbd65d4836b04d97b3d8c6a79c7896100428f59a509eb1e27c863597c08dc2455e265e75d53b7543b67ef48cecb39306

data/.editorconfig

@@ -0,0 +1,12 @@
+[*]
+charset = utf-8
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.json]
+indent_size = 2
+
+[*.{yaml,yml}]
+indent_size = 2

data/.gitignore

@@ -0,0 +1,167 @@
+# Created by https://www.gitignore.io/api/ruby,git,windows,linux,osx,vim,sublimetext
+
+### Ruby ###
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+
+### Git ###
+*.orig
+
+
+### Windows ###
+# Windows image file caches
+Thumbs.db
+ehthumbs.db
+
+# Folder config file
+Desktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+
+### OSX ###
+*.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+
+### Vim ###
+# swap
+[._]*.s[a-w][a-z]
+[._]s[a-w][a-z]
+# session
+Session.vim
+# temporary
+.netrwhist
+*~
+# auto-generated tag files
+tags
+
+
+### SublimeText ###
+# cache files for sublime text
+*.tmlanguage.cache
+*.tmPreferences.cache
+*.stTheme.cache
+
+# workspace files are user-specific
+*.sublime-workspace
+
+# project files should be checked into the repository, unless a significant
+# proportion of contributors will probably not be using SublimeText
+# *.sublime-project
+
+# sftp configuration file
+sftp-config.json
+
+# Package control specific files
+Package Control.last-run
+Package Control.ca-list
+Package Control.ca-bundle
+Package Control.system-ca-bundle
+Package Control.cache/
+Package Control.ca-certs/
+bh_unicode_properties.cache
+
+# Sublime-github package stores a github token in this file
+# https://packagecontrol.io/packages/sublime-github
+GitHub.sublime-settings
+
+### Custom rules ###
+# Ignore access token file
+access_token.txt

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,8 @@
+sudo: false
+
+language: ruby
+
+rvm:
+  - 2.3.1
+
+before_install: gem install bundler -v 1.12.5

data/.yardopts

@@ -0,0 +1,5 @@
+--protected
+--private
+--markup-provider=redcarpet
+--markup=markdown
+'lib/**/*.rb' - README.md LICENSE

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ratrix.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 by Adam Hellberg.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,63 @@
+chatrix
+=======
+
+A Ruby implementation of the [Matrix][matrix] API.
+
+## License
+
+Copyright (c) 2016 by Adam Hellberg.
+
+chatrix is licensed under the [MIT License][license-url], see the file
+`LICENSE` for more information.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'chatrix'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install chatrix
+
+## Usage
+
+This implementation is currently very basic and exposes all the endpoints
+in the `Matrix` class. Example usage:
+
+```ruby
+# Uses the standard matrix.org homeserver
+api = Chatrix::Matrix.new 'my secret token'
+
+# Join may raise ForbiddenError if client does not have permission
+# to join the room
+if id = api.join '#myroom:myserver.org'
+  api.send_message id, 'Hello everyone!'
+end
+```
+
+Currently there is no asynchronous calls or built-in handling of
+rate-limiting.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake spec` to run the tests. You can also run `bin/console`
+for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub][issues].
+
+[project]: https://github.com/Sharparam/chatrix
+[issues]: https://github.com/Sharparam/chatrix/issues
+[matrix]: http://matrix.org
+[license-url]: http://opensource.org/licenses/MIT

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: [:spec, :rubocop]

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'chatrix'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'pry'
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/chatrix.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'chatrix/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'chatrix'
+  spec.version       = Chatrix::VERSION
+  spec.authors       = ['Adam Hellberg']
+  spec.email         = ['sharparam@sharparam.com']
+
+  spec.summary       = 'Ruby implementation of the Matrix API'
+  # spec.description   = %q{}
+  spec.homepage      = 'https://github.com/Sharparam/chatrix'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'httparty', '~> 0.13'
+
+  spec.add_development_dependency 'bundler', '~> 1.12'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'pry', '~> 0.10'
+  spec.add_development_dependency 'yard', '~> 0.8'
+  spec.add_development_dependency 'redcarpet', '~> 3.3'
+  spec.add_development_dependency 'rubocop', '~> 0.40.0'
+end

data/lib/chatrix.rb

@@ -0,0 +1,7 @@
+require 'chatrix/version'
+require 'chatrix/errors'
+require 'chatrix/matrix'
+
+# Encapsulates all gem functionality.
+module Chatrix
+end

data/lib/chatrix/errors.rb

@@ -0,0 +1,54 @@
+module Chatrix
+  # Generic faults from the library.
+  class ChatrixError < StandardError
+  end
+
+  # Errors that stem from an API call.
+  class ApiError < ChatrixError
+  end
+
+  # Error raised when a request is badly formatted.
+  class RequestError < ApiError
+    attr_reader :code, :api_message
+
+    def initialize(error)
+      @code = error['errcode']
+      @api_message = error['error']
+    end
+  end
+
+  # Raised when a resource is requested that the user does not have access to.
+  class ForbiddenError < ApiError
+  end
+
+  # Raised when a resource is not found.
+  class NotFoundError < ApiError
+  end
+
+  # Raised when a user is not found.
+  class UserNotFoundError < NotFoundError
+    attr_reader :username
+
+    def initialize(username)
+      @username = username
+    end
+  end
+
+  # Raised when a user's avatar is not found.
+  class AvatarNotFoundError < NotFoundError
+    attr_reader :username
+
+    def initialize(username)
+      @username = username
+    end
+  end
+
+  # Raised when a room is not found.
+  class RoomNotFoundError < NotFoundError
+    attr_reader :room
+
+    def initialize(room)
+      @room = room
+    end
+  end
+end

data/lib/chatrix/matrix.rb

@@ -0,0 +1,730 @@
+require 'chatrix/errors'
+
+require 'httparty'
+
+module Chatrix
+  # Provides an interface to the Matrix API on a homeserver.
+  #
+  # Detailed information about the data structures is not included here and
+  # can be found on the
+  # {http://matrix.org/docs/api/client-server Matrix API page}.
+  #
+  # @note Any of the methods may raise the errors listed in {#parse_response}.
+  #   Consider this when calling the methods.
+  # @note Endpoints that require a room ID in the official API can be passed
+  #   a room alias in this implementation, the room ID will be automatically
+  #   looked up from the homeserver.
+  #
+  # @todo Try to extract functionality to make this class smaller.
+  #
+  # rubocop:disable ClassLength
+  class Matrix
+    include HTTParty
+
+    headers('User-Agent' => "chatrix/#{Chatrix::VERSION}",
+            'Content-Type' => 'application/json',
+            'Accept' => 'application/json')
+
+    # Maps HTTP methods to their respective HTTParty method.
+    METHODS = {
+      get: -> (path, options, &block) { get path, options, &block },
+      put: -> (path, options, &block) { put path, options, &block },
+      post: -> (path, options, &block) { post path, options, &block },
+      delete: -> (path, options, &block) { delete path, options, &block }
+    }.freeze
+
+    # Default homeserver used if none is specified.
+    DEFAULT_HOMESERVER = 'https://matrix.org'.freeze
+
+    # API path used.
+    API_PATH = '/_matrix/client/r0'.freeze
+
+    # @!attribute access_token
+    #   @return [String] The access token used when performing requests
+    #     to the homeserver.
+    attr_accessor :access_token
+
+    # @!attribute [r] homeserver
+    #   @return [String] The homeserver for this API object.
+    attr_reader :homeserver
+
+    # Initializes a new instance of Matrix.
+    #
+    # @param token [String] The access token to use.
+    # @param homeserver [String] The homeserver to make requests to.
+    def initialize(token = nil, homeserver = DEFAULT_HOMESERVER)
+      @homeserver = homeserver
+      @base_uri = @homeserver + API_PATH
+      @transaction_id = 0
+      @access_token = token
+    end
+
+    # 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
+
+    # 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(user)
+      make_request(:get, "/profile/#{user}").parsed_response
+    rescue NotFoundError
+      raise UserNotFoundError.new(user), '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
+      raise AvatarNotFoundError.new(user), 'Avatar or user could not be found'
+    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
+      raise UserNotFoundError.new(user), '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
+    #   {#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
+
+    # 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 (ID or alias).
+    # @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_room_tags(user, room)
+      room = get_room_id room if room.start_with? '#'
+      make_request(:get, "/user/#{user}/rooms/#{room}/tags")['tags']
+    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_room_id #get_room_id is an example of how this method could be
+    #   used to get a room's ID.
+    def get_room_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
+
+    # 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_room_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)
+      room = get_room_id room if room.start_with? '#'
+      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_room_members(room)
+      room = get_room_id room if room.start_with? '#'
+      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_room_messages(room, from, direction, limit = 10)
+      room = get_room_id room if room.start_with? '#'
+      make_request(
+        :get,
+        "/rooms/#{room}/messages",
+        params: {
+          from: from,
+          dir: direction,
+          limit: limit
+        }
+      ).parsed_response
+    end
+
+    # Sends a message object to a room.
+    #
+    # @param room [String] The room to send to.
+    # @param content [Hash] The message content to send.
+    # @param type [String] The type of message to send.
+    # @return [String] The event ID of the sent message is returned.
+    # @see #send_message_type
+    # @see #send_message
+    # @see #send_emote
+    # @see #send_notice
+    # @see #send_html
+    def send_message_raw(room, content, type = 'm.room.message')
+      room = get_room_id room if room.start_with? '#'
+      @transaction_id += 1
+      make_request(
+        :put,
+        "/rooms/#{room}/send/#{type}/#{@transaction_id}",
+        content: content
+      )['event_id']
+    end
+
+    # A helper method to send a simple message construct.
+    #
+    # @param room [String] The room to send the message to.
+    # @param content [String] The message to send.
+    # @param type [String] The type of message this is.
+    # @return (see #send_message_raw)
+    # @see #send_message
+    # @see #send_notice
+    # @see #send_emote
+    # @see #send_html
+    def send_message_type(room, content, type = 'm.text')
+      send_message_raw room, msgtype: type, body: content
+    end
+
+    # Sends a plaintext message to a room.
+    #
+    # @param room [String] The room to send to.
+    # @param content [String] The message to send.
+    # @return (see #send_message_raw)
+    #
+    # @example Sending a simple message
+    #   send_message('#party:matrix.org', 'Hello everyone!')
+    def send_message(room, content)
+      send_message_type room, content
+    end
+
+    # Sends a notice message to a room.
+    #
+    # @param room [String] The room to send to.
+    # @param content [String] The message to send.
+    # @return (see #send_message_raw)
+    #
+    # @example Sending a notice
+    #   send_notice('#stuff:matrix.org', 'This is a notice')
+    def send_notice(room, content)
+      send_message_type room, content, 'm.notice'
+    end
+
+    # Sends an emote to a room.
+    #
+    # `/me <message here>`
+    #
+    # @param room [String] The room to send to.
+    # @param content [String] The emote to send.
+    # @return (see #send_message_raw)
+    #
+    # @example Sending an emote
+    #   # Will show up as: "* <user> is having fun"
+    #   send_emote('#party:matrix.org', 'is having fun')
+    def send_emote(room, content)
+      send_message_type room, content, 'm.emote'
+    end
+
+    # Sends a message formatted using HTML markup.
+    #
+    # The `body` field in the content will have the HTML stripped out, and is
+    # usually presented in clients that don't support the formatting.
+    #
+    # The `formatted_body` field in the content will contain the actual HTML
+    # formatted message (as passed to the `html` parameter).
+    #
+    # @param room [String] The room to send to.
+    # @param html [String] The HTML formatted text to send.
+    # @return (see #send_message_raw)
+    #
+    # @example Sending an HTML message
+    #   send_html('#html:matrix.org', '<strong>Hello</strong> <em>world</em>!')
+    def send_html(room, html)
+      send_message_raw(
+        room,
+        msgtype: 'm.text',
+        format: 'org.matrix.custom.html',
+        body: html.gsub(%r{</?[^>]*?>}, ''), # TODO: Make this better
+        formatted_body: html
+      )
+    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_room_state(room, type = nil, key = nil)
+      room = get_room_id room if room.start_with? '#'
+
+      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 message to the server informing it about a user having started
+    # or stopped typing.
+    #
+    # @param room [String] The affected room.
+    # @param user [String] The user that started or stopped typing.
+    # @param typing [Boolean] Whether the user is typing.
+    # @param duration [Fixnum] How long the user will be typing for
+    #   (in milliseconds).
+    # @return [Boolean] `true` if the message sent successfully, otherwise
+    #   `false`.
+    def send_typing(room, user, typing = true, duration = 30_000)
+      room = get_room_id room if room.start_with? '#'
+
+      content = { typingState: { typing: typing, timeout: duration } }
+
+      make_request(
+        :put,
+        "/rooms/#{room}/typing/#{user}",
+        content: content
+      ).code == 200
+    end
+
+    # Synchronize with the latest state on the server.
+    #
+    # For initial sync, call this method with the `since` parameter
+    # set to `nil`.
+    #
+    # @param filter [String,Hash] The ID of a filter to use, or provided
+    #   directly as a hash.
+    # @param since [String,nil] A point in time to continue sync from.
+    #   Will retrieve a snapshot of the state if not set, which will also
+    #   provide a `next_batch` value to use for `since` in the next call.
+    # @param full_state [Boolean] If `true`, all state events will be returned
+    #   for all rooms the user is a member of.
+    # @param set_presence [Boolean] If `true`, the user performing this request
+    #   will have their presence updated to show them as being online.
+    # @param timeout [Fixnum] Maximum time (in milliseconds) to wait before
+    #   the request is aborted.
+    # @return [Hash] The initial snapshot of the state (if no `since` value
+    #   was provided), or a delta to use for updating state.
+    def sync(filter: nil, since: nil, full_state: false,
+             set_presence: true, timeout: 30_000)
+      options = { full_state: full_state }
+
+      options[:since] = since if since
+      options[:set_presence] = 'offline' unless set_presence
+      options[:timeout] = timeout if timeout
+
+      if filter.is_a? Integer
+        options[:filter] = filter
+      elsif filter.is_a? Hash
+        options[:filter] = URI.encode filter.to_json
+      end
+
+      make_request(:get, '/sync', params: options).parsed_response
+    end
+
+    # Joins a room on the homeserver.
+    #
+    # @param room [String] The room to join.
+    # @param third_party_signed [Hash,nil] If provided, the homeserver must
+    #   verify that it matches a pending `m.room.third_party_invite` event in
+    #   the room, and perform key validity checking if required by the event.
+    # @return [String] The ID of the room that was joined is returned.
+    def join(room, third_party_signed = nil)
+      if third_party_signed
+        make_request(
+          :post,
+          "/join/#{room}",
+          content: { third_party_signed: third_party_signed }
+        )['room_id']
+      else
+        make_request(:post, "/join/#{room}")['room_id']
+      end
+    end
+
+    # Kicks and bans a user from a room.
+    #
+    # @param room [String] The room to ban the user from.
+    # @param user [String] The user to ban.
+    # @param reason [String] Reason why the ban was made.
+    # @return [Boolean] `true` if the ban was carried out successfully,
+    #   otherwise `false`.
+    #
+    # @example Banning a spammer
+    #   ban('#haven:matrix.org', '@spammer:spam.com', 'Spamming the room')
+    def ban(room, user, reason)
+      room = get_room_id room if room.start_with? '#'
+      make_request(
+        :post,
+        "/rooms/#{room}/ban",
+        content: { reason: reason, user_id: user }
+      ).code == 200
+    end
+
+    # Forgets about a room.
+    #
+    # @param room [String] The room to forget about.
+    # @return [Boolean] `true` if the room was forgotten successfully,
+    #   otherwise `false`.
+    def forget(room)
+      room = get_room_id room if room.start_with? '#'
+      make_request(:post, "/rooms/#{room}/forget").code == 200
+    end
+
+    # Kicks a user from a room.
+    #
+    # This does not ban the user, they can rejoin unless the room is
+    # invite-only, in which case they need a new invite to join back.
+    #
+    # @param room [String] The room to kick the user from.
+    # @param user [String] The user to kick.
+    # @param reason [String] The reason for the kick.
+    # @return [Boolean] `true` if the user was successfully kicked,
+    #   otherwise `false`.
+    #
+    # @example Kicking an annoying user
+    #   kick('#fun:matrix.org', '@anon:4chan.org', 'Bad cropping')
+    def kick(room, user, reason)
+      room = get_room_id room if room.start_with? '#'
+      make_request(
+        :post,
+        "/rooms/#{room}/kick",
+        content: { reason: reason, user_id: user }
+      ).code == 200
+    end
+
+    # Leaves a room (but does not forget about it).
+    #
+    # @param room [String] The room to leave.
+    # @return [Boolean] `true` if the room was left successfully,
+    #   otherwise `false`.
+    def leave(room)
+      room = get_room_id room if room.start_with? '#'
+      make_request(:post, "/rooms/#{room}/leave").code == 200
+    end
+
+    # Unbans a user from a room.
+    #
+    # @param room [String] The room to unban the user from.
+    # @param user [String] The user to unban.
+    # @return [Boolean] `true` if the user was successfully unbanned,
+    #   otherwise `false`.
+    def unban(room, user)
+      room = get_room_id room if room.start_with? '#'
+      make_request(
+        :post,
+        "/rooms/#{room}/unban",
+        content: { user_id: user }
+      ).code == 200
+    end
+
+    # Performs a login attempt.
+    #
+    # @note A successful login will update the {#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
+      @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 API calls.
+    #
+    # @return [Hash] The response from the server (an empty hash).
+    def logout
+      response = make_request :post, '/logout'
+
+      # A successful logout means the access token has been invalidated
+      @access_token = nil
+
+      response.parsed_response
+    end
+
+    # Gets a new access token to use for API calls when the current one
+    # expires.
+    #
+    # @note On success, the internal {#access_token access_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 }
+      )
+
+      @access_token = response['access_token']
+      @refresh_token = response['refresh_token']
+
+      response.parsed_response
+    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 {#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
+
+    # 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 rooms(from: 'START', to: 'END', limit: 10, direction: 'b')
+      make_request(
+        :get,
+        '/publicRooms',
+        params: {
+          from: start,
+          to: to,
+          limit: limit,
+          dir: direction
+        }
+      ).parsed_response
+    end
+
+    private
+
+    # Create an options Hash to pass to a server request.
+    #
+    # This method embeds the {#access_token access_token} into the
+    # query parameters.
+    #
+    # @param params [Hash{String=>String},nil] Query parameters to add to
+    #   the options hash.
+    # @param content [Hash,nil] Request content to add to the options hash.
+    # @return [Hash] Options hash ready to be passed into a server request.
+    def make_request_options(params, content)
+      options = {
+        query: @access_token ? { access_token: @access_token } : {}
+      }
+
+      options[:query].merge!(params) if params.is_a? Hash
+      options[:body] = content.to_json if content.is_a? Hash
+
+      options
+    end
+
+    # Helper method for performing requests to the homeserver.
+    #
+    # @param method [Symbol] HTTP request method to use. Use only symbols
+    #   available as keys in {METHODS}.
+    # @param path [String] The API path to query, relative to the base
+    #   API path, eg. `/login`.
+    # @param params [Hash{String=>String}] Additional parameters to include
+    #   in the query string (part of the URL, not put in the request body).
+    # @param content [Hash] Content to put in the request body, must
+    #   be serializable to json via `#to_json`.
+    # @yield [fragment] HTTParty will call the block during the request.
+    #
+    # @return [HTTParty::Response] The HTTParty response object.
+    def make_request(method, path, params: nil, content: nil, &block)
+      path = @base_uri + URI.encode(path)
+      options = make_request_options params, content
+
+      parse_response METHODS[method].call(path, options, &block)
+    end
+
+    # Parses a HTTParty Response object and returns it if it was successful.
+    #
+    # @param response [HTTParty::Response] The response object to parse.
+    # @return [HTTParty::Response] The same response object that was passed
+    #   in, if the request was successful.
+    #
+    # @raise [ForbiddenError] If a `403` response code was returned from the
+    #   request.
+    # @raise [NotFoundError] If a `404` response code was returned from the
+    #   request.
+    # @raise [RequestError] If an error object was returned from the server.
+    # @raise [ApiError] If an unparsable error was returned from the server.
+    #
+    # rubocop:disable MethodLength
+    def parse_response(response)
+      case response.code
+      when 200 # OK
+        response
+      when 403 # Forbidden
+        raise ForbiddenError, 'You do not have access to that resource'
+      when 404 # Not found
+        raise NotFoundError, 'The specified resource could not be found'
+      else
+        if %w{(errcode), (error)}.all? { |k| response.include? k }
+          raise RequestError.new(response.parsed_response), 'Request failed'
+        end
+
+        raise ApiError, 'Unknown API error occurred when carrying out request'
+      end
+    end
+  end
+end

data/lib/chatrix/version.rb

@@ -0,0 +1,4 @@
+module Chatrix
+  # The current version of this gem.
+  VERSION = '1.0.0.pre'.freeze
+end

metadata

@@ -0,0 +1,173 @@
+--- !ruby/object:Gem::Specification
+name: chatrix
+version: !ruby/object:Gem::Version
+  version: 1.0.0.pre
+platform: ruby
+authors:
+- Adam Hellberg
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-06-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.40.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.40.0
+description: 
+email:
+- sharparam@sharparam.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- ".yardopts"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- chatrix.gemspec
+- lib/chatrix.rb
+- lib/chatrix/errors.rb
+- lib/chatrix/matrix.rb
+- lib/chatrix/version.rb
+homepage: https://github.com/Sharparam/chatrix
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Ruby implementation of the Matrix API
+test_files: []
+has_rdoc: