gitter-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3324810a0534c18ad4957d40b6b4cc97f52f424fdcf2a111f3ac0b3dcf41e5be
+  data.tar.gz: 90ae6c39f509fcd48b1c818b18ebb8eb58d3b3b71215d194e2d1bfcb49397596
+SHA512:
+  metadata.gz: a211a4432bd3cbac69976e99f87a498778040b77277ab019c6bf6bae810a078cab5271801ae5718ed77ccd74b5e95f1855c845d141bd0a68022322feeb63d1bb
+  data.tar.gz: 3462797ccbd1771b6dd11df29d7689099d0365e2d22047223815d5a7b3115d8c09dafd15013c8397f78c4b3b775e35ee20da711b515f482a606472f6469baa67

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Nick LaMuro
+
+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,176 @@
+gitter-api-ruby
+===============
+
+A ruby client for the [gitter][] API.
+
+Includes an `ActiveRecord`-like interface with models that are parsed from
+the responses, as well as a lower level request/json-response interface.
+
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'gitter-api-ruby'
+```
+
+And then execute:
+
+```console
+$ bundle
+```
+
+Or install it yourself as:
+
+```console
+$ gem install gitter-api-ruby
+```
+
+
+Usage
+-----
+
+### Client Setup
+
+The `Gitter::API::Client` is the main http component, and is in charge of auth
+and configuration of the base endpoint.
+
+In most cases, only a token is needed for the client instance:
+
+``` ruby
+client = Gitter::API::Client.new :token => "1a2b3c4d5e6f7a8b9c0d"
+```
+
+### Configuration
+
+There are a few tunables that can be configured globally, or for each instance
+of `Gitter::API::Client`:
+
+``` ruby
+Config.api_prefix
+#=> "/v1"
+Config.api_url
+#=> "https://api.gitter.im"
+Config.ssl_verify
+#=> false
+
+Config.api_prefix = "/api/v1"
+client = Gitter::API::Client.new :api_uri => URI("http://localhost:4000")
+client.api_prefix
+#=> "/api/v1"
+client.api_url
+#=> "https://api.gitter.im"
+client.ssl_verify
+#=> false
+```
+
+### Making requests
+
+`Gitter::API::Client` provides `ActiveRecord`-like response objects for each of
+it's high level methods found on the client itself, as well as what is
+available from the returned objects:
+
+```ruby
+# Fetching the configured user:
+client.user
+#=> #<Gitter::API::User:0x00007ff49b293c01 ... >
+
+# Fetch rooms/private chats for the configured user
+client.user.rooms
+client.rooms # equivalent with the above, but memoized to the client object
+#=> #<Gitter::API::Room::Collection:0x00007ff49b293c02 ... >
+
+# API Collections are Enumerable
+client.rooms.map(&:uri)
+#=> ["gitterHQ/sandbox", "gitterHQ/api"]
+
+client.rooms.first
+#=> #<Gitter::API::Room:0x00007ff49b293c03 ... >
+
+# Advanced example:
+#
+# print the first 50 chars of the last 5 messages from each room
+client.rooms.each do |room|
+  puts room.name
+  puts "-" * room.name.size
+
+  puts room.messages(:limit => 5).map {|msg| "@#{msg.user.username}: #{msg.text[0, 50]}..." }
+  puts
+end
+#=> gitterHQ/api
+#=> ----------------
+#=> @alice: Hey...
+#=> @bob: Hi...
+#=> @alice: I stole your identity...
+#=> @bob: Oh... that isn't good...
+#=> @bob: Good thing I am a fictional user, huh...
+#=>
+#=> gitterHQ/sandbox
+#=> ------------
+#=> ...
+```
+
+Not everything is currently implemented by the client, but for everything else,
+the raw `.get`, `.post`, and `.put` methods of the client are available to
+execute requests on those missing endpoints:
+
+```ruby
+# Note:  `/v1/users/me` (plural form) is a dummy route... do not use
+client.get "/v1/user/me"
+#=> { "user" => "NickLaMuro", "id" => ... }
+
+# Bulk "mark messages as read" for a particular room to reduce number of http
+# requests
+#
+# https://developer.gitter.im/docs/user-resource#mark-unread-items-as-read
+#
+# (currently not a high level method for this, only for single messages)
+room          = client.rooms.first
+msg_ids       = room.unread_messages.map(&:id)
+payload       = { "chat" => msg_ids }
+mark_read_uri = "/v1/user/#{client.user.id}/rooms/#{room.id}/unreadItems"
+
+client.post mark_read_uri, payload
+```
+
+
+### Developer Setup
+
+Clone as you would...
+
+This plugin requires zero dependencies to work with (besides what is included
+with ruby for a while now), so there is nothing required to install and get
+setup.
+
+However, to work with the gitter API, you will need on of two things:
+
+- A local running copy of [gitter-webapp][]
+- An API key from the public instance of [gitter][]
+
+The first option has a pretty lengthy setup process, so that will not be
+covered here, but a viable option if you don't want to make a mess of a
+community room while doing your testing.
+
+For the section option, it doesn't take much:
+
+1. Grab your API key from https://developer.gitter.im/apps
+2. Save it as a one line file in top level of this repo: `.gitter.token`
+3. Run `rake console`
+
+From there, `client` is a configured `Gitter::API::Client` instance for you to
+start testing with.
+
+
+TODO
+----
+
+- Implement missing top-level functions (user bans, leave rooms, etc.)
+- Support app client keys (is this different at all?)
+- Add integration tests (run a local copy of gitter)
+- CI testing
+
+
+[gitter]:        https://gitter.im
+[gitter-webapp]: https://gitlab.com/gitlab-org/gitter/webapp

data/lib/gitter/api.rb

@@ -0,0 +1,27 @@
+require 'gitter/api/version'
+require 'gitter/api/client'
+
+module Gitter # :nodoc:
+  # = gitter-api-ruby
+  #
+  # A ruby gitter api client library
+  #
+  # == Classes
+  #
+  # See the below classes for more information.
+  #
+  # === Client
+  #
+  # * +Gitter::API::Client+
+  #
+  # === Models
+  #
+  # * +Gitter::API::User+
+  # * +Gitter::API::Room+
+  # * +Gitter::API::Message+
+  #
+  # :main:
+  #
+  module API
+  end
+end

data/lib/gitter/api/base.rb

@@ -0,0 +1,37 @@
+module Gitter
+  module API
+    # Base model that other +Gitter::API+ models inherit from
+    #
+    # See:
+    #
+    # - +Gitter::API::Message+
+    # - +Gitter::API::Room+
+    # - +Gitter::API::User+
+    #
+    class Base
+      # Configured client that fetched the record
+      #
+      # Used for subsequent calls (instance methods)
+      #
+      attr_reader :client
+
+      # All models should call this in their overrides, and configure their
+      # specific model attributes in the override from the +@data+ that was passed
+      # in.
+      #
+      # Note: +@data+ is set, but is not a formal accessor.  Currently just
+      # available for debugging if needed.
+      #
+      def initialize client, data # :nodoc:
+        @client = client
+        @data   = data
+      end
+
+      # Helper method for fetching the API prefix from the client
+      #
+      def api_prefix
+        client.api_prefix
+      end
+    end
+  end
+end

data/lib/gitter/api/client.rb

@@ -0,0 +1,121 @@
+require "json"
+
+require 'gitter/api/util/net_http_client'
+
+require 'gitter/api/config'
+require 'gitter/api/collectable'
+
+# models
+require 'gitter/api/base'
+require 'gitter/api/user'
+require 'gitter/api/room'
+require 'gitter/api/message'
+
+module Gitter
+  module API
+    # The +Gitter::API::Client+ is the main http component, and is in charge of auth
+    # and configuration of the base endpoint of the gitter API that is being
+    # connected to and interacted with.
+    #
+    # == Usage
+    #
+    # === Client Setup
+    #
+    # In most cases, only a token is needed for the client instance:
+    #
+    #   client = Gitter::API::Client.new :token => "1a2b3c4d5e6f7a8b9c0d"
+    #
+    # === Example Queries
+    #
+    # Fetching the configured user:
+    #
+    #   client.user
+    #   #=> #<Gitter::API::User:0x00007ff49b293c01 ... >
+    #
+    # Fetch rooms/private chats for the configured user:
+    #
+    #   client.rooms
+    #   client.user.rooms # same as client.rooms, but is not memoized
+    #   #=> #<Gitter::API::Room::Collection:0x00007ff49b293c02 ... >
+    #
+    # API Collections are Enumerable:
+    #
+    #   client.rooms.map(&:uri)
+    #   #=> ["gitterHQ/sandbox", "gitterHQ/api"]
+    #
+    # See individual model classes for more examples
+    #
+    #
+    # == Additional methods
+    #
+    # +Gitter::API::User+ and +Gitter::API::Room+ each provide methods that are
+    # included in the client as base methods.  Refer to those classes for more
+    # info.
+    #
+    class Client
+
+      include Net::HTTP::RestClientModule
+
+      include User::ClientMethods
+      include Room::ClientMethods
+
+      # See Gitter::API::Config#api_uri
+      attr_reader :api_uri
+
+      # See Gitter::API::Config#api_prefix
+      attr_reader :api_prefix
+
+      # Client User API token
+      attr_reader :auth_token
+
+      # See Gitter::API::Config#ssl_verify
+      attr_reader :ssl_verify
+
+      # Set for +Net::HTTP::RestClientModule+
+      #
+      alias uri api_uri # :nodoc:
+
+      # Initialize a new +Gitter::API::Client+
+      #
+      # Aside from :token, all other options will be defaulted to what is
+      # configured in +Gitter::API::Config+
+      #
+      # See +Gitter::API::Config+ for defaults.
+      #
+      # ==== Options
+      #
+      # (symbol keys only)
+      #
+      # [*:token* (String)]       (required) Auth token for the API client user
+      #
+      # [*:api_prefix* (String)]  Path prefix for all API routes
+      # [*:api_uri* (URI)]        Endpoint URI of the configured gitter API
+      # [*:ssl_verify* (Boolean)] Indicates if net/http should verify ssl certs
+      #
+      def initialize options = {}
+        @api_prefix = options[:api_prefix] || Config.api_prefix
+        @api_uri    = options[:api_uri]    || Config.api_uri
+        @auth_token = options[:token]
+        @ssl_verify = options.key? :ssl_verify ? options[:ssl_verify] : Config.ssl_verify
+      end
+
+      private
+
+      # Override of the default in Net::HTTP::RestClientModule
+      #
+      def response_builder response
+        JSON.parse response.body
+      end
+
+      # Override of the default in Net::HTTP::RestClientModule
+      #
+      def default_headers
+        @headers ||= {
+          "Accept"        => "application/json",
+          "Content-Type"  => "application/json",
+          "Authorization" => "Bearer #{auth_token}"
+        }
+      end
+    end
+  end
+end

data/lib/gitter/api/collectable.rb

@@ -0,0 +1,97 @@
+module Gitter
+  module API
+    # = Gitter::API::Collectable
+    #
+    # This is a support module for Gitter::API models that allows for defining
+    # a subclass based on the included class that is a Enumberable collection
+    # of base class, in a similar vein to how ActiveRecord::Relation is used to
+    # represent a collection of ActiveRecord objects.
+    #
+    # Allows for initializing on a shared interface where only the +parent+ and
+    # +data+ blob (array of hash data objects for the given base record) need
+    # to be passed in.
+    #
+    # For models that have different initialization argument schema (e.g.
+    # Gitter::API::Message), this collectable_args can be defined on the
+    # included class that will override the args passed to +.new+ when
+    # instanciating each record in the collection.
+    #
+    # == Example Usage
+    #
+    # For Gitter::API::User, this is pretty straight forward:
+    #
+    #   class Gitter::API::User
+    #     include Collectable
+    #   end
+    #
+    # But for Gitter::API::Message, since +room_id+ needs to be supplied for
+    # that class, it has `collectable_args` defined to support that when
+    # instanciating the collection.
+    #
+    #   class Gitter::API::Message
+    #     include Collectable
+    #
+    #     def self.collectable_args parent, item_data # :nodoc:
+    #       room_id = parent.respond_to? :room_id ? parent.room_id : nil
+    #       [parent.client, room_id, item_data]
+    #     end
+    #   end
+    #
+    # So when each message is created it will receive +client+, +room_id+, and
+    # +data+ as arguments for each object instanciated instead of the default
+    # +client+ and +data+ only.
+    #
+    module Collectable # :nodoc: all
+
+      # Defines the following on the newly created sub class
+      #
+      # - .base_class
+      # - .initialize (new)
+      # - #collectable_args (used in initialize)
+      # - #each
+      # - #last
+      # - #parent (used in collectable_args)
+      #
+      def self.included base_class
+        collection_class = Class.new
+        collection_class.send :include, Enumerable
+        collection_class.instance_variable_set :@base_class, base_class
+
+        collection_class.module_eval <<-CLASS
+          def self.base_class
+            @base_class
+          end
+
+          def initialize parent, data
+            @parent = parent
+            @items  = data.map do |item_data|
+                        self.class.base_class.new *(collectable_args item_data)
+                      end
+          end
+
+          def collectable_args item_data
+            if self.class.base_class.respond_to? :collectable_args
+              self.class.base_class.collectable_args parent, item_data
+            else
+              [parent.client, item_data]
+            end
+          end
+
+          def each
+            @items.each { |item| yield item }
+          end
+
+          def last
+            @items.last
+          end
+
+          def parent
+            @parent
+          end
+        CLASS
+
+        base_class.const_set :Collection, collection_class
+      end
+    end
+  end
+end

data/lib/gitter/api/config.rb

@@ -0,0 +1,85 @@
+module Gitter
+  module API
+    # A singleton class for holding on to default values for the
+    # Gitter::API::Client for the given session.
+    #
+    # When making changes here, it will affect every Gitter::API::Client that
+    # is configured going forward, unless the values are changed on client
+    # instanciation via the config hash.
+    #
+    # == Tunable attributes
+    #
+    # - +api_prefix+
+    # - +api_url+
+    # - +ssl_verify+
+    #
+    #
+    class Config
+      # API prefix for production https://api.gitter.im ("/v1")
+      DEFAULT_API_PREFIX = "/v1"
+
+      # Default API URL ("https://api.gitter.im")
+      DEFAULT_API_URL    = "https://api.gitter.im"
+
+      class << self
+        # Path prefix for API routes
+        #
+        # Generally in development (localhost), "/api/v1" should be used instead
+        # of the default ("/v1")
+        attr_accessor :api_prefix
+
+        # Endpoint URL for the Gitter API
+        attr_accessor :api_url
+
+        # Whether or not to verify SSL certs (default is +true+)
+        #
+        # Set to +false+ when using +localhost+ (development) since a local
+        # server most likely will not have valid https certs
+        attr_accessor :ssl_verify
+
+        # :doc:
+        # The prefix for the API endpoints (default: +/v1+)
+        #
+        # In development using a local gitter instance, it should be +/api/v1+,
+        # but in production it is just +/v1+
+        def api_prefix
+          @api_url || DEFAULT_API_PREFIX
+        end
+
+        # :doc:
+        # Endpoint URL for the Gitter API (default: "https://api.gitter.im")
+        #
+        # For local instances of +gitter-webapp+, the URL can then be set to
+        # +http://localhost:5000+.
+        #
+        def api_url
+          @api_url || DEFAULT_API_URL
+        end
+
+        # :doc:
+        # Reset the reference for @api_url
+        #
+        # Also clears the cache for +@api_uri+
+        #
+        def api_url= url
+          @api_url = url
+          @api_uri = nil # clear @api_uri cache when @api_url is set
+        end
+
+        # :doc:
+        # URI object cache of the api_url
+        #
+        def api_uri
+          @api_uri ||= URI(api_url)
+        end
+
+        # :doc:
+        # If the base endpoint should verify SSL cert (default: true)
+        #
+        def ssl_verify
+          @ssl_verify || true
+        end
+      end
+    end
+  end
+end

data/lib/gitter/api/message.rb

@@ -0,0 +1,136 @@
+module Gitter
+  module API
+    # Model representation of the +/room/:room_id/chatMessages*+ REST endpoints
+    # in the gitter API
+    #
+    class Message < Base
+      include Collectable
+
+      # See Gitter::API::Collectable
+      #
+      def self.collectable_args parent, item_data # :nodoc:
+        room_id = parent.respond_to? :room_id ? parent.room_id : nil
+
+        [parent.client, room_id, item_data]
+      end
+
+      # Message id (from gitter)
+      attr_reader :id
+
+      # +Gitter::API::User+ that sent the message
+      attr_reader :user
+
+      # Original message in plain-text/markdown
+      attr_reader :text
+
+      # HTML formatted message (formatted on the API server)
+      attr_reader :html
+
+      # Indicates if the message has been read by the client user
+      attr_reader :unread
+
+      # Number of users that have read the message
+      attr_reader :read_by
+
+      # ISO formatted date of when the message originally sent
+      attr_reader :created_at
+
+      # ISO formatted data of when the message was edited last (if it has been)
+      attr_reader :updated_at
+
+      # List of +Gitter::API::User+ mentioned in the message
+      attr_reader :mentions
+
+      # List of github issues referened in the message
+      attr_reader :issues
+
+      # List of URLs present in the message
+      attr_reader :urls
+
+      # *INTERNAL* *METHOD*
+      #
+      # Initialize a new +Gitter::API::Message+
+      #
+      # Used by +Gitter::API::Room+ when fetching messages, so favor using that
+      # instead.
+      #
+      # ==== Parameters
+      #
+      # *Note:*  messages in the Gitter schema don't have a `room_id`, so that
+      # is passed in as an additional arg here.
+      #
+      # [*client* (Gitter::API::Client)] Configured client object
+      # [*room_id* (String)]             Room ID message came from
+      # [*data* (Hash)]                  Initialization data
+      #
+      # ==== Options
+      #
+      # (string keys only)
+      #
+      # [*id* (String)]            Message id
+      # [*user* (String)]          +Gitter::API::User+ that sent the message
+      # [*text* (String)]          Original message in plain-text/markdown
+      # [*html* (String)]          HTML formatted message
+      # [*unread* (Boolean)]       Indicates if current user has read the message
+      # [*read_by* (Integer)]      Number of users that have read the message
+      # [*created_at* (Date)]      ISO formatted date of the message
+      # [*updated_at* (Date)]      ISO formatted date of the message if edited
+      # [*mentions* (Array<User>)] +Gitter::API::User+(s) mentioned in message
+      # [*issues* (Array<String>)] List of #Issues referenced in the message
+      # [*urls* (Array<String>)]   List of URLs present in message
+      #
+      def initialize client, room_id, data
+        super client, data
+
+        @room_id    = room_id
+
+        @id         = data["id"]
+        @user       = User.new client, data["fromUser"]
+        @text       = data["text"]
+        @html       = data["html"]
+        @unread     = data["unread"]
+
+        @read_by    = data["readBy"]
+        @created_at = data["sent"]
+        @updated_at = data["editedAt"]
+
+        @mentions   = data["mentions"].map { |user| User.new client, user }
+        @issues     = data["issues"]
+        @urls       = data["urls"]
+      end
+
+      # Edit/update a Message's text
+      #
+      # The html will be reformated on the server, and returned as part of the
+      # +data+ when returned.
+      #
+      # A new instance of Gitter::API::Message is the turn value
+      #
+      # :return: Gitter::API::Message
+      #
+      # ==== Parameters
+      #
+      # [*text* (String)] New text to update the message record to
+      #
+      def update text
+        payload = { "text" => message }.to_json
+        data    = client.post "#{api_prefix}/rooms/#{room_id}/chatMessages/#{id}", payload
+
+        new client, room_id, data
+      end
+
+      # Mark the message as read for the client user
+      #
+      # :return: true
+      #
+      def mark_as_read
+        payload = { "chat" => [id] }.to_json
+        path    = "/#{api_prefix}/user/#{client.user.id}/rooms/#{room_id}/unreadItems"
+
+        client.post path, payload
+
+        true
+      end
+    end
+  end
+end

data/lib/gitter/api/room.rb

@@ -0,0 +1,267 @@
+module Gitter
+  module API
+    # Model representation of the +/room/:room_id/*+ REST endpoints in the
+    # gitter API
+    #
+    class Room < Base
+      include Collectable
+
+      # Room id
+      attr_reader :id
+
+      # Room name
+      attr_reader :name
+
+      # Room topic
+      attr_reader :topic
+
+      # Indicates if the room is a one on one chat
+      attr_reader :one_on_one
+
+      # Indicates if the room is configured with notifications for the user
+      attr_reader :lurk
+
+      # Indicates if the room is public
+      attr_reader :public
+
+      # Number of unread mentions for this room
+      attr_reader :mentions
+
+      # Number of users in the room
+      attr_reader :user_count
+
+      # Number of unread messages for this room
+      attr_reader :unread_items
+
+      # Array of tags for the room
+      attr_reader :tags
+
+      # Room URI on gitter
+      attr_reader :uri
+
+      # Room url
+      attr_reader :url
+
+      # Used by Collectable
+      alias room_id id # :nodoc:
+
+      # Find a room given a URI
+      #
+      # See Gitter::API::Room::ClientMethods#find_room
+      #
+      # ==== Parameters
+      #
+      # [*uri* (String)] Room URI on Gitter
+      #
+      # ==== Example
+      #
+      #   client.find "gitterhq/sandbox"
+      #   #=> <#Gitter::API::Room name="gitterhq/sandbox" ...>
+      #
+      # :return: Gitter::API::Room
+      #
+      def self.find uri
+        Client.find_room uri
+      end
+
+      # *INTERNAL* *METHOD*
+      #
+      # Initialize a new Gitter::API::Room
+      #
+      # Use Gitter::API::Room::ClientMethods (found of Gitter::API::Client) to
+      # initialize and make use of the instance methods.
+      #
+      # ==== Parameters
+      #
+      # [*client* (Gitter::API::Client)] Configured client object
+      # [*data* (Hash)]                  Initialization data
+      #
+      # ==== Options
+      #
+      # (string keys only)
+      #
+      # [*id* (String)]            Room id
+      # [*name* (String)]          Room name
+      # [*topic* (String)]         Room topic
+      # [*one_on_one* (Boolean)]   Indicates if one on one chat
+      # [*lurk* (Boolean)]         Indicates if notifications disabled
+      # [*public* (Boolean)]       Indicates if public room
+      # [*unread_items* (Integer)] Number of unread messages
+      # [*mentions* (Integer)]     Number of unread mentions
+      # [*user_count* (Integer)]   Number of users in the room
+      # [*tags* (Array<String>)]   Tags that define the room
+      # [*uri* (String)]           Room URI on Gitter
+      # [*url* (String)]           Path to the room on gitter
+      #
+      def initialize client, data
+        super
+
+        @id           = data["id"]
+        @name         = data["name"]
+        @topic        = data["topic"]
+        @one_on_one   = data["oneOnOne"]
+        @lurk         = data["lurk"]
+        @public       = data["public"]
+        @mentions     = data["mentions"]
+        @user_count   = data["userCount"]
+        @unread_items = data["unreadItems"]
+        @tags         = data["tags"]
+        @uri          = data["uri"]
+        @url          = data["url"]
+      end
+
+      # List users of a room
+      #
+      # ==== Options
+      #
+      # [*:search* (String)]  Filter based on search query
+      # [*:limit* (Integer)]  Limit number of records returned
+      # [*:skip* (Integer)]   Return users after skiping N records
+      #
+      # :return: Gitter::API::User::Collection
+      #
+      def users options = {}
+        query = {
+          "skip"     => options[:skip],
+          "limit"    => options[:limit],
+          "q"        => options[:search]
+        }
+
+        data = client.get "/#{api_prefix}/rooms/#{id}/users", query
+
+        User::Collection.new self, data
+      end
+
+      # List recent messages of a room
+      #
+      # ==== Options
+      #
+      # [*:search* (String)]  Filter based on search query
+      # [*:before* (String)]  Limit messages to before a date
+      # [*:after* (String)]   Limit messages to after a date
+      # [*:around* (String)]  Limit messages to around a date
+      # [*:limit* (Integer)]  Limit number of records returned
+      # [*:skip* (Integer)]   Return users after skiping N records
+      #
+      # Returns a collection of most recent messages, with the oldest of that
+      # collection being first in the returned list.
+      #
+      # :return: Gitter::API::User::Collection
+      #
+      def messages options = {}
+        query = {
+          "skip"     => options[:skip],
+          "beforeId" => options[:before],
+          "afterId"  => options[:after],
+          "aroundId" => options[:around],
+          "limit"    => options[:limit],
+          "q"        => options[:search]
+        }
+
+        data = client.get "/v1/rooms/#{id}/chatMessages", query
+
+        Message::Collection.new self, data
+      end
+
+      # Join the current room
+      #
+      # :return: Gitter::API::Room
+      #
+      def join
+        payload = { "id" => id }.to_json
+        data    = client.post "#{api_prefix}/user/#{client.user.id}/rooms", payload
+
+        self
+      end
+
+      # Send a message to the current room
+      #
+      # ==== Parameters
+      #
+      # [*message* (String)] Message to send to the room
+      #
+      # Messages should be in plain text/mardown format, and will be converted
+      # to html on the server side.
+      #
+      # :return: Gitter::API::Message
+      #
+      def send_message message
+        payload = { "text" => message }.to_json
+        data    = client.post "#{api_prefix}/rooms/#{id}/chatMessages", payload
+
+        Message.new client, id, data
+      end
+
+      # Unread messages in the room for the current user
+      #
+      # :return: Gitter::API::Message::Collection
+      #
+      def unread_messages
+        data = client.get "#{api_prefix}/user/#{client.user.id}/rooms/#{id}/unreadItems"
+
+        Message::Collection.new self, data
+      end
+
+      # +Gitter::API::Room+ based methods that are available on any
+      # +Gitter::API::Client+ instance
+      #
+      module ClientMethods
+        # Memoized version of User#rooms for the api client user
+        #
+        # ==== Parameters
+        #
+        # [*refresh* (Boolean)] set to true refresh memoization
+        #
+        # :return: Gitter::API::Room::Collection
+        #
+        def rooms refresh = false
+          return @rooms unless @rooms.nil? || refresh
+
+          @rooms = user.rooms
+        end
+
+        # Find a room based off of uri
+        #
+        # ==== Parameters
+        #
+        # [*uri* (String)] Room URI on Gitter
+        #
+        # ==== Example
+        #
+        #   client.join_room "gitterhq/sandbox"
+        #   #=> <#Gitter::API::Room name="gitterhq/sandbox" ...>
+        #
+        # :return: Gitter::API::Room
+        #
+        def find_room uri
+          payload =  { "uri" => uri }.to_json
+          data    = self.post "#{api_prefix}/rooms", payload
+
+          Room.new(self, data)
+        end
+
+        # Join a room from the top level client using the api user
+        #
+        # ==== Parameters
+        #
+        # [*uri* (String)] Room URI on Gitter
+        #
+        # ==== Example
+        #
+        #   client.join_room "gitterhq/sandbox"
+        #   #=> <#Gitter::API::Room name="gitterhq/sandbox" ...>
+        #
+        # :return: Gitter::API::Room
+        #
+        def join_room uri
+          has_room = rooms.detect { |room| room.uri == uri }
+
+          return has_room if has_room
+
+          @rooms = nil # clear rooms cache
+          self.class.find_room(uri).join
+        end
+      end
+    end
+  end
+end

data/lib/gitter/api/user.rb

@@ -0,0 +1,78 @@
+module Gitter
+  module API
+    # Model representation of the +/user/*+ REST endpoints in the gitter API
+    #
+    class User < Base
+      include Collectable
+
+      # ID (from the API)
+      attr_reader :id
+
+      # Name of the user
+      attr_reader :display_name
+
+      # Username (minus the '@')
+      attr_reader :username
+
+      # The relative path the the user's page in the gitter webapp
+      attr_reader :url
+
+      # *INTERNAL* *METHOD*
+      #
+      # Initialize a new +Gitter::API::User+
+      #
+      # <tt>Gitter::API::Client#user</tt> will return on of these objects, as
+      # well as some methods on +Gitter::API::Room+ and when instanciating a
+      # +Gitter::API::Message+, so favor instanciating that way.
+      #
+      # ==== Parameters
+      #
+      # [*client* (Gitter::API::Client)] Configured client object
+      # [*data* (Hash)]                  Initialization data
+      #
+      # ==== Options
+      #
+      # (string keys only)
+      #
+      # [*id* (String)]           User id
+      # [*display_name* (String)] Gitter/GitHub user real name
+      # [*username* (String)]     Gitter/GitHub username (without '@')
+      # [*url* (String)]          Path to the user on Gitter
+      #
+      def initialize client, data
+        super
+
+        @id           = data["id"] || data["userId"]
+        @display_name = data["displayName"]
+        @username     = data["username"] || data["screenName"]
+        @url          = data["url"]
+      end
+
+      # Fetch the all of the room records for a given user
+      #
+      # Includes one on one conversations, since those are considered "rooms"
+      # as well (based on their schema)
+      #
+      # Returns a Gitter::API::Room::Collection
+      def rooms
+        data = client.get "#{api_prefix}/rooms"
+
+        Room::Collection.new self, data
+      end
+
+      # +Gitter::API::User+ based methods that are available on any
+      # +Gitter::API::Client+ instance
+      module ClientMethods
+        # Fetch the configured user
+        #
+        # Returns a Gitter::API::User instance
+        def user refresh = false
+          return @user unless @user.nil? || refresh
+
+          data  = get "#{api_prefix}/user/me"
+          @user = User.new self, data
+        end
+      end
+    end
+  end
+end

data/lib/gitter/api/util/net_http_client.rb

@@ -0,0 +1,148 @@
+require "net/http"
+
+module Net # :nodoc:
+  class HTTP # :nodoc:
+    # == Net::HTTP::RestClientModule
+    #
+    # A wrapper library for NetHTTP to create a simplistic "Rest Client" class
+    #
+    # Simply `include Net::HTTP::RestClientModule` into a class, and make sure
+    # on initialization a `uri` method/accessor with a `URI` object is created.
+    #
+    #     class MyRestClient
+    #       include Net::HTTP::RestClientModule
+    #
+    #       attr_accessor :uri
+    #
+    #       def initialize
+    #         @uri = URI("http://example.com")
+    #       end
+    #
+    #       # override this if needed, otherewise true by default
+    #       def ssl_verify
+    #         !!ENV["SHOULD_SSL_VERIFY"]
+    #       end
+    #     end
+    #
+    #     # calling
+    #     MyRestClient.new.get  "/foo/bar"
+    #     MyRestClient.new.post "/foo/bar"
+    #     MyRestClient.new.put  "/foo/bar"
+    #
+    #--
+    #
+    # TODO:  Make query_params a little more generic
+    # TODO:  Create a gem for this simple lib
+    #
+    module RestClientModule
+
+      # +Net::HTTP+ Connection object for the client object
+      #
+      # Will conigure it based off of the +uri+ method/accessor of current
+      # instance if one has not been instanciated yet.
+      #
+      def connection
+        return @connection if defined? @connection
+
+        verify_ssl = respond_to?(:ssl_verify) ? ssl_verify : true
+
+        @connection             = Net::HTTP.new(uri.host, uri.port)
+        @connection.use_ssl     = true                      if uri.scheme == "https"
+        @connection.verify_mode = OpenSSL::SSL::VERIFY_NONE unless verify_ssl
+
+        @connection
+      end
+
+      # Send a +GET+ request to the configured +connection+
+      #
+      # ==== Parameters
+      #
+      # [*path* (String)]          URL path for the request
+      # [*query_params* (Hash)]    Query params to add to the path
+      # [*request_headers* (Hash)] Request specific headers
+      #
+      def get path, query_params = {}, request_headers = {}
+        if query_params.delete_if { |_,v| v.nil? }.empty?
+          get_uri = path
+        else
+          uri_class = uri.scheme == "https" ? URI::HTTPS : URI::HTTP
+          get_uri   = uri_class.build :host  => uri.host,
+                                      :path  => path,
+                                      :query => URI.encode_www_form(query_params)
+        end
+
+        get_headers = headers request_headers
+        get_request = Net::HTTP::Get.new get_uri, get_headers
+
+        connection_do get_request
+      end
+
+      # Send a +POST+ request to the configured +connection+
+      #
+      # ==== Parameters
+      #
+      # [*path* (String)]          URL path for the request
+      # [*payload* (Hash)]         Request body
+      # [*request_headers* (Hash)] Request specific headers
+      #
+      def post path, payload, request_headers = {}
+        post_headers      = headers request_headers
+        post_request      = Net::HTTP::Post.new path, post_headers
+        post_request.body = payload
+
+        connection_do post_request
+      end
+
+      # Send a +PUT+ request to the configured +connection+
+      #
+      # ==== Parameters
+      #
+      # [*path* (String)]          URL path for the request
+      # [*payload* (Hash)]         Request body
+      # [*request_headers* (Hash)] Request specific headers
+      #
+      def put path, payload, request_headers = {}
+        put_headers      = headers request_headers
+        put_request      = Net::HTTP::Put.new path, put_headers
+        put_request.body = payload
+
+        connection_do put_request
+      end
+
+      private
+
+      # Helper for executing a request and building a response
+      def connection_do req
+        # puts "connection_do: #{req.method} #{req.path}"  # debugging...
+        response = connection.start {|http| http.request req }
+        response_builder response
+      end
+
+      # Helper for building headers for a request
+      def headers request_headers = {}
+        default_headers.dup.merge request_headers
+      end
+
+      # :doc:
+      #
+      # Format and return a response
+      #
+      # Default return value is the +Net::HTTP::Request+ body, but the
+      # +response_builder+ method can be overwritten to configure out the data
+      # for a request is returned
+      def response_builder response
+        response.body
+      end
+
+      # :doc:
+      #
+      # Default headers for each request
+      #
+      # Can be overwritten in the included class to allow for specific headers
+      # to be added to every request (Auth headers, Accept headers, etc.)
+      def default_headers
+        {}
+      end
+    end
+  end
+end

data/lib/gitter/api/version.rb

@@ -0,0 +1,5 @@
+module Gitter
+  module API
+    VERSION = "0.1.0" # :nodoc:
+  end
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: gitter-api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nick LaMuro
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-01-09 00:00:00.000000000 Z
+dependencies:
+- !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: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: |
+  A ruby client for the gitter (https://gitter.im) API.
+
+  Includes an `ActiveRecord`-like interface with models that are parsed from
+  the responses, as well as a lower level request/json-response interface.
+email:
+- nicklamuro@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/gitter/api.rb
+- lib/gitter/api/base.rb
+- lib/gitter/api/client.rb
+- lib/gitter/api/collectable.rb
+- lib/gitter/api/config.rb
+- lib/gitter/api/message.rb
+- lib/gitter/api/room.rb
+- lib/gitter/api/user.rb
+- lib/gitter/api/util/net_http_client.rb
+- lib/gitter/api/version.rb
+homepage: https://github.com/NickLaMuro/gitter-api-ruby
+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: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: An(other) Ruby API client for Gitter
+test_files: []