hubkit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 645c28ca63135ba2eb911fce4e0f759db34be764
+  data.tar.gz: db3abc9ba844450b14555e9cb743989d21896b03
+SHA512:
+  metadata.gz: b63ffe491f25e4c10ebed01fbc6284e37f1a9f5ac99e1d6af79d08342b2a237362888623641259b1d1ee89e854eed3fa19b5789b245aedd4fdabc6871f91d469
+  data.tar.gz: 5859fd0c38ae794734299634298dfe1a8607545eee5d162f4544463488655c019a929cba670429a0688e2b8dca564e0159233f0647095d8033f7cdc33e069cf4

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

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

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at robert@revelry.co. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Setup for Development
+
+```
+bundle install
+```
+
+should be sufficient to install dependencies.
+
+You will a `.env` file with your API keys to record new tests against the
+API. Your API key will be omitted from the test cassettes by VCR. The format for
+`.env` is:
+
+```
+GITHUB_TOKEN=YOUR-API-TOKEN
+```
+
+# Submitting Changes
+
+1. Fork the repository.
+2. Set up the gem per the instructions above and ensure `bundle exec rake spec`
+   runs cleanly.
+3. Create a topic branch.
+4. Add specs for your unimplemented feature or bug fix.
+5. Run `bundle exec rake spec`. If your specs pass, return to step 4.
+6. Implement your feature or bug fix.
+7. Re-run `bundle exec rake spec`. If your specs fail, return to step 6.
+8. Open coverage/index.html. If your changes are not completely covered by the
+   test suite, return to Step 4.
+9. Thoroughly document and comment your code.
+10. Run `bundle exec rake doc:yard` and make sure your changes are documented.
+11. Add, commit, and push your changes.
+12. Submit a pull request.

data/Gemfile

@@ -0,0 +1,17 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hubkit.gemspec
+gemspec
+
+group :development, :test do
+  gem 'byebug'
+  # rubocop:disable Style/ExtraSpacing
+  gem 'cucumber',  '~> 2.1'
+  gem 'dotenv'
+  gem 'rspec',     '~> 3.5.0'
+  gem 'rspec-collection_matchers'
+  gem 'simplecov', '~> 0.11.2'
+  gem 'vcr',       '~> 2.6'
+  gem 'webmock',   '~> 1.17.3'
+  gem 'yard',      '~> 0.8.7'
+end

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2017 Robert Prehn
+
+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,38 @@
+# Hubkit
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/hubkit`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hubkit'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hubkit
+
+## Usage
+
+TODO: Write usage instructions here
+
+## 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.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/prehnRA/hubkit. Check out [CONTRIBUTING.md](https://github.com/prehnRA/hubkit/blob/master/CONTRIBUTING.md) for more info.
+
+Everyone is welcome to participate in the project. We expect contributors to
+adhere the Contributor Covenant Code of Conduct (see [CODE_OF_CONDUCT.md](https://github.com/prehnRA/hubkit/blob/master/CODE_OF_CONDUCT.md)).
+
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "hubkit"
+
+# 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 "irb"
+IRB.start(__FILE__)

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/hubkit.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hubkit/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "hubkit"
+  spec.version       = Hubkit::VERSION
+  spec.authors       = ["Robert Prehn"]
+  spec.email         = ["robert@revelry.co"]
+  spec.licenses    = ['MIT']
+
+  spec.summary       = "Higher level abstractions for querying the github API"
+  spec.description   = <<-DESC
+    Hubkit provides methods for querying the github API at a higher level than
+    making individual API calls. Think of it like an ORM for the github API.
+  DESC
+
+  spec.homepage      = "https://github.com/prehnRA/hubkit"
+
+  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_dependency 'github_api', '~> 0.16.0'
+  spec.add_dependency 'activesupport', '>= 4', '< 6'
+
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/hubkit.rb

@@ -0,0 +1,33 @@
+require 'active_support/core_ext/module'
+require 'active_support/core_ext/object'
+require 'active_support/json'
+require 'active_support/time'
+
+require 'github_api'
+require 'hubkit/configuration'
+require 'hubkit/chainable_collection'
+require 'hubkit/paginator'
+require 'hubkit/cooldowner'
+require 'hubkit/event_collection'
+require 'hubkit/event_paginator'
+require 'hubkit/issue_collection'
+require 'hubkit/issue_paginator'
+require 'hubkit/issue'
+require 'hubkit/logger'
+require 'hubkit/repo_collection'
+require 'hubkit/repo_paginator'
+require 'hubkit/repo'
+require 'hubkit/version'
+
+# Main module of the hubkit library. This is generally not used directly, but
+# through a subclass such as Hubkit::IssueCollection, Hubkit::EventCollection,
+# Hubkit::Repo, etc.
+module Hubkit
+  class << self
+    # Return the Github client used by the library
+    # @return [Github::Client] the github API client
+    def client
+      Configuration.client
+    end
+  end
+end

data/lib/hubkit/chainable_collection.rb

@@ -0,0 +1,106 @@
+module Hubkit
+  # @abstract A class which wraps an array (or Enumerable) and provides convenience
+  # methods for chainable filters, e.g.:
+  # @example
+  #     repo.issues.unassigned.labeled('in progress')
+  class ChainableCollection
+    # Allows definition of new chainable filters within the class definition
+    # @example
+    #   scope :unlabeled, -> { |collection| collection.reject(&:labeled?) }
+    # @param [String, Symbol] name the anem of the method
+    # @yieldparam ... any arguments needed by the block
+    def self.scope(name, &block)
+      define_method name do |*args|
+        wrap(
+          instance_exec(*args, &block),
+        )
+      end
+    end
+
+    # Create a new ChainableCollection
+    # @param [Enumerable] inner the collection which will be wrapped in the
+    #   Hubkit::ChainableCollection
+    def initialize(inner)
+      @inner = inner
+    end
+
+    # Return a Hubkit::ChainableCollection containing all members for which
+    # the block is true. This new Hubkit::ChainableCollection will also be
+    # filterable in the same way.
+    # @yieldparam item the item to be evaluated by the block
+    def select(&block)
+      return wrap(@inner.select &block) if block_given?
+      wrap(@inner.select)
+    end
+
+    # Return a collection of the same type as `self`, containing `items`
+    # @param [Enumberable] items the items to be contained in the new
+    #   collection
+    def wrap(items)
+      self.class.new(items)
+    end
+
+    # Check if a method is implemented by either this method or the wrapped
+    # collection
+    # @param [String, Symbol] name the name of the method to check
+    # @param [Boolean] include_all if true, will include private methods
+    # @return [Boolean] returns true if the collection or the wrapped
+    #   collection implements the method
+    def respond_to?(name, include_all = false)
+      super || @inner.respond_to?(name)
+    end
+
+    # Call into the wrapped collection if a method has not been implemented
+    # on the ChainableCollection
+    # @param [String, Symbol] name the name of the method being called
+    # @param [Array] args the arguments to the method being called
+    # @yieldparam ... the parameters of the any block given to the method
+    #   which is being called
+    # @return the value of the method on the inner collection as called
+    def method_missing(name, *args, &block)
+      return super unless @inner.respond_to?(name)
+      @inner.send(name, *args, &block)
+    end
+
+    # Returns a collection which will contain all elements which are contained
+    # in this ChainableCollection, but NOT matching any additional chained filters
+    # @example
+    #   ChainableCollection.new([1, 2, 3, 4]).not.select(&:odd?) # even->[2, 4]
+    # @return [NotCollection] a collection which contains all elements of self
+    #   which don't match additional filters
+    def not
+      NotCollection.new(self)
+    end
+
+    # Returns true if the other collection contains the same elements
+    # @param [Enumerable] other collection to compare with
+    # @return [Boolean] true if this collection and the other contain the same
+    #   elements
+    def ==(other)
+      other == self.to_a
+    end
+  end
+
+  # A collection that lets you perform the inverse of a filter
+  # @example
+  #     repo.issues.not.labeled('in progress')
+  class NotCollection
+    def initialize(base)
+      @base = base
+    end
+
+    # Any method of this class will be delegated down to the original
+    # ChainableCollection. The result of the method will be a
+    # ChainableCollection which contains all the elements not returned
+    # by the filter called.
+    # @param [String, Symbol] name the name of the method being called
+    # @param [Array] args the arguments to the method being called
+    # @yieldparam ... the parameters of the any block given to the method
+    #   which is being called
+    # @return [ChainableCollection] all elements which do not match the chained
+    #   filter in a new ChainableCollection
+    def method_missing(name, *args, &block)
+      @base.wrap(@base - @base.send(name, *args, &block))
+    end
+  end
+end

data/lib/hubkit/configuration.rb

@@ -0,0 +1,51 @@
+module Hubkit
+  # Hold the configuration of the Hubkit library. Holds the client, default
+  # github organization, and the github library configuration options.
+  # @attr [Github::Client] client the underlying Github client used for library
+  #   operations
+  # @attr [String] default_org the github organization that will be used if
+  #   none is specified
+  # @attr [Hash] github_config the configuration to use for the github client
+  #   as a Hash
+  module Configuration
+    class << self
+      attr_writer :client
+      attr_accessor :default_org
+      attr_accessor :github_config
+
+      # Set configuration for the library
+      # @param [Hash] opts the configuration options to set
+      # @yieldparam [Hubkit::Configuration] this configuration, which is passed
+      #   to the block
+      # @return [Github::Client] the github client to be used by the library
+      def configure(opts = {}, &block)
+        hubkit_config = self
+        @client = Github.new do |github_config|
+          hubkit_config.github_config = github_config
+          yield hubkit_config
+        end
+      end
+
+      # The underlying Github::Client that will be used for library operations
+      # @return [Github::Client] a Github::Client which will be used for
+      #   library operations
+      def client
+        @client || Github.new
+      end
+
+      # Pass through all method calls which are not implemented directly on the
+      # Configuration to the client's configuration method
+      # @param [String, Symbol] name the name of the method which is being called
+      # @param [Array] args the array of arguments to the method
+      # @yieldparam ... any arguments to the block required by the underlying
+      #   Github::Client method
+      # @return the same return value that the github configuration would return
+      def method_missing(name, *args, &block)
+        if github_config.present? && github_config.respond_to?(name, false)
+          return github_config.public_send(name, *args, &block)
+        end
+        super
+      end
+    end
+  end
+end

data/lib/hubkit/cooldowner.rb

@@ -0,0 +1,20 @@
+module Hubkit
+  # An object that handles Github rate throttling by setting a delay and then
+  # retrying a block
+  class Cooldowner
+    # Perform an action, and if Github rejects it due to rate limit, sleep and
+    # try again later
+    # @yield
+    def self.with_cooldown
+      cooldown = 1
+      begin
+        yield
+      rescue Github::Error::Forbidden => e
+        Logger.warn "Sleeping for abuse (#{cooldown} seconds)"
+        sleep cooldown
+        cooldown = [2 * cooldown, 10].min
+        retry
+      end
+    end
+  end
+end

data/lib/hubkit/event_collection.rb

@@ -0,0 +1,58 @@
+module Hubkit
+  # A collection of GitHub events with chainable filters
+  class EventCollection < ChainableCollection
+    # Put the list of events in reverse chronological order
+    # @return [EventCollection] the events in reverse chronological order
+    def reverse_chronological
+      wrap(
+        sort do |a, b|
+          Time.parse(b['created_at']) <=> Time.parse(a['created_at'])
+        end,
+      )
+    end
+
+    # Put the list of events in chronological order
+    # @return [EventCollection] the events in chronological order
+    def chronological
+      wrap(
+        sort do |a, b|
+          Time.parse(a['created_at']) <=> Time.parse(b['created_at'])
+        end,
+      )
+    end
+
+    # Filter to all the events which occur between start_dt and end_date,
+    # inclusive
+    # @param [Date, DateTime] start_dt the beginning of the included period (inclusive)
+    # @param [Date, DateTime] end_date the end of the included period (inclusive)
+    # @return [EventCollection] the events falling in the window
+    def between(start_dt, end_date)
+      wrap(
+        @inner.select do |event|
+          stamp = Time.parse(event['created_at'])
+          stamp >= start_dt && stamp <= end_date
+        end,
+      )
+    end
+
+    # Filter to all events where an issue was labeled with a given label
+    # @param [String] label the label to search for
+    # @return [EventCollection] a collection containing all events where an
+    #   issue was labeled with the given label
+    def labeled(label)
+      wrap(
+        @inner.select do |event|
+          event['event'] == 'labeled' &&
+            event['label'].name.downcase == label.downcase
+        end,
+      )
+    end
+
+    # Filter to all events where an issue was closed
+    # @return [EventCollection] a collection containing all events where an
+    #   issue was closed
+    def closed
+      wrap(@inner.select { |event| event.event == 'closed' })
+    end
+  end
+end

data/lib/hubkit/event_paginator.rb

@@ -0,0 +1,36 @@
+module Hubkit
+  # Returns all events for a GitHub issues-- for example, labeling, unlabeling,
+  # closing, etc-- and handle pagination for you
+  class EventPaginator < Paginator
+    include Enumerable
+
+    # Initialize a new paginator for events from the API
+    # @param [String] org the github organization which contains the repo for
+    #   which we'll gather events
+    # @param [String] repo the github repo name for which we'll gather events
+    # @param [optional Fixnum] issue_number if present, the number of the issue
+    #   for which we'll sfind events
+    def initialize(org:, repo:, issue_number: nil)
+      @org = org
+      @repo = repo
+      @issue_number = issue_number
+
+      opts =
+        if issue_number.present?
+          { issue_number: issue_number }
+        else
+          {}
+        end
+
+      super() do |i|
+        Cooldowner.with_cooldown do
+          Hubkit.client.issues.events.list(
+            @org,
+            @repo,
+            opts.merge(page: i),
+          )
+        end
+      end
+    end
+  end
+end

data/lib/hubkit/issue.rb

@@ -0,0 +1,185 @@
+module Hubkit
+  # Represents one issue in github
+  # @attr [String] org the github organization name of the issue
+  # @attr [String] repo the github repo name
+  # @attr [Fixnum] number the issue's number
+  class Issue
+    # A regex which matches a textual name of an issue i.e. dingus/123 or
+    # foobar/dingus/123
+    ISSUE_PATTERN = %r{
+      (
+        (?<org>[^/]+)/(?<repo>[^/]+)
+        |
+        (?<repo>[^/]+)
+      )
+      /
+      (?<number>[0-9]+)
+    }x
+
+    # Create an Issue model from the textual name of the issue
+    # @example
+    #   Hubkit::Issue.from_name('foobar/dingus/123')
+    # @param [String] name a string name for an issue, like dingus/123 or
+    #   foobar/dingus/123
+    # @return [Hubkit::Issue] the issue matching this org, repo, and number
+    def self.from_name(name)
+      new(**parameters_from_name(name))
+    end
+
+    # Parse an issue name into org, repo, and number
+    # @param [String] name a string like dingus/123 or foobar/dingus/123
+    # @return [Hash] a hash containing org:, repo:, and number: values
+    def self.parameters_from_name(name)
+      match_data = Issue::ISSUE_PATTERN.match(name)
+      {
+        org: match_data[:org] || Hubkit::Configuration.default_org,
+        repo: match_data[:repo],
+        number: match_data[:number],
+      }
+    end
+
+    # Create an Issue model from a github api payload. Preseeds the github
+    # payload of the model to avoid refetching from the API later.
+    # @param [String] org the github organization of the issue
+    # @param [String] repo the repo name of the issue
+    # @param [Hash] gh the payload hash from the API
+    def self.from_gh(org:, repo:, gh:)
+      new(org: org, repo: repo, number: gh['number']).tap do |issue|
+        issue.instance_variable_set(:@_to_gh, gh)
+      end
+    end
+
+    attr_accessor :org, :repo, :number
+
+    # Create a new issue model
+    # @param [String] org the github organization name of the issue
+    # @param [String] repo the github repo name
+    # @param [Fixnum] number the issue's number
+    def initialize(org:, repo:, number:)
+      @org = org
+      @repo = repo
+      @number = number
+    end
+
+    # The issue payload from the github API
+    # @return [Github::Mash] a hash-like object of the github API response
+    def to_gh
+      @_to_gh ||= Github.issues.get(@org, @repo, @number).body
+    end
+
+    # A list of all of the current labels of the issue
+    # @return [Enumerable] the list of labels
+    def labels
+      @_labels ||= to_gh['labels'].map { |label| label.name.downcase }
+    end
+
+    # Add a label to an issue
+    # @param [String] label the label to add to the issue
+    # @return [Enumerable] the new list of labels including the addition
+    def label!(label)
+      Hubkit.client.issues.labels.add @org, @repo, @number, label
+      labels.append(label).uniq!
+    end
+
+    # Remove a label from an issue
+    # @yieldparam [String] label_name a current label. if the block returns
+    #   true, this label will be removed from the list
+    # @return [Enumerable] the new list of labels after any removals
+    def unlabel!(&block)
+      fail('Block is required for unlabel') unless block_given?
+      to_gh.labels.map(&:name)
+      .select do |label_name|
+        yield label_name
+      end
+      .each do |label_name|
+        Hubkit.client.issues.labels.remove @org, @repo, @number, label_name: label_name
+        labels.delete(label_name)
+      end
+      labels
+    end
+
+    delegate :title, :number, :body, to: :to_gh
+
+    # Returns true if the issue is a pull request
+    # @return [Boolean] true if the issue is a pull request, otherwise false
+    def pull?
+      to_gh['pull_request'].present?
+    end
+
+    # Returns true if the issue is not a pull request
+    # @return [Boolean] false if the issue is a pull request, otherwise true
+    def true_issue?
+      !pull?
+    end
+
+    # Returns the time at which the issue was labeled `label`. It will return
+    # the time of the latest such event.
+    # @param [String] label the label to search for
+    # @return [Date] the date when that issue was labeled such.
+    def when_labeled(label)
+      return unless events.labeled(label).any?
+      Time.parse(events.labeled(label).first['created_at'])
+    end
+
+    # Returns when the issue was opened
+    # @return [DateTime] the DateTime when the issue was created
+    def when_opened
+      Time.parse(created_at)
+    end
+
+    # Returns when the issue was closed
+    # @return [DateTime] the DateTime when the issue was closed
+    def when_closed
+      return unless events.closed.any?
+      Time.parse(events.closed.first['created_at'])
+    end
+
+    # The EventCollection of events related to this Issue
+    # @return [EventCollection] the events for this issue, in reverse chronological order
+    def events
+      @_events ||=
+        EventCollection.new(
+          event_paginator,
+        )
+        .reverse_chronological
+    end
+
+    # Returns a paginator for fetching all events for this issue
+    # @return [EventPaginator] the paginator for fetching all events for this issue
+    def event_paginator
+      EventPaginator.new(
+        org: @org,
+        repo: @repo,
+        issue_number: @number,
+      )
+    end
+
+    # Return the list of usernames of every user ever assigned to an issue
+    # @return [Enumerable] the usernames of the users which have been assigned
+    #   to the issue
+    def users_ever_assigned
+      events
+        .select { |event| event.event == 'assigned' }
+        .map { |event| event.assignee.login }
+        .uniq
+    end
+
+    # A plaintext version of the issue, with the name, title, and body
+    # @return [String] a string containing the name, title, and body, suitable
+    #   for uses like export or chat integration
+    def to_text
+      "#{number}: #{title}\n---\n#{body}\n"
+    end
+
+    # Allow access to elements of the github payload by calling the names as
+    # methods
+    # @param [String, Symbol] name
+    # @param [Array] args should be empty, only needed to match the expected
+    #   signature from Ruby
+    # @return the value of to_gh[name]
+    def method_missing(name, *args, &block)
+      return to_gh[name] if args.length == 0 && !block_given? && to_gh.key?(name)
+      super
+    end
+  end
+end

data/lib/hubkit/issue_collection.rb

@@ -0,0 +1,101 @@
+module Hubkit
+  # A collection of GitHub issues with chainable filters
+  class IssueCollection < ChainableCollection
+    # Filters to issues which where at some point labeled with the given label
+    # regardless of whether it currently has that label or not
+    # @param [String] label the label in question
+    # @return [IssueCollection] a collection of issues which were ever labeled
+    #   with that label
+    def ever_labeled(label)
+      wrap(
+        @inner.select do |issue|
+          issue.when_labeled(label).present?
+        end,
+      )
+    end
+
+    # Return a collection of issues which are open
+    # @return [IssueCollection] the issues in the collection which are open
+    def open
+      wrap(@inner.select { |issue| issue.state == "open" })
+    end
+
+    # Return a collection of issues which are closed
+    # @return [IssueCollection] the issues in the collection which are closed
+    def closed
+      wrap(@inner.select { |issue| issue.state == "closed" })
+    end
+
+    # Return a collection of issues which are labeled with any of the given
+    # labels
+    # @param [Enumerable, String] labels if a string, then this is the single
+    #   label used to filter issues. If it is an enumerable set of strings,
+    #   any issues matching any of the labels will be returned.
+    # @return [IssueCollection] a collection of matching the label
+    def labeled(labels)
+      return wrap(labels.flat_map { |label| labeled(label) }) if labels.respond_to?(:map)
+
+      wrap(@inner.select do |issue|
+        issue.labels.include?(labels.downcase)
+      end)
+    end
+
+    # Return a collection of issues which are not labeled
+    # @return [IssueCollection] a collection of issues without labels
+    def unlabeled
+      wrap(@inner.select { |issue| issue.labels.empty? })
+    end
+
+    # Return a collection of issues which have labels matching a pattern
+    # @param [Regex] label_pattern a pattern which issues must match to be
+    #   included in the collection
+    # @return [IssueCollection] a collection of issues with labels matching
+    #   the pattern
+    def labeled_like(label_pattern)
+      wrap(@inner.select do |issue|
+        issue.labels.any? { |label| label_pattern.match(label) }
+      end)
+    end
+
+    # Return issues which are not pull requests
+    # @return [IssueCollection] a collection of issues which are not pull
+    #   requests
+    def true_issues
+      wrap(@inner.select(&:true_issue?))
+    end
+
+    # Return issues which are pull requests
+    # @return [IssueCollection] a collection of issues which are pull requests
+    def pulls
+      wrap(@inner.select(&:pull?))
+    end
+
+    # Return issues which are unassigned
+    # @return [IssueCollection] a collection of issues which are unassigned
+    def unassigned
+      wrap(@inner.select { |issue| issue.assignee.nil? })
+    end
+
+    # Returns issues opened within a date window between start_dt and end_dt
+    # @param [Date] start_dt the beginning date of the filter window (inclusive)
+    # @param [Date] end_dt the end date of the filter window (exclusive)
+    # @return [IssueCollection] a collection of issues opened within the window
+    def opened_between(start_dt, end_dt)
+      wrap(
+        @inner.select do |issue|
+          start_dt <= issue.when_opened && issue.when_opened < end_dt
+        end,
+      )
+    end
+
+    # Group the issue collection by the current assignee
+    # @return [Hash] a hash, where the assignee's username is the key, and the
+    #   values are IssueCollections of issues assigned to that user
+    def by_assignee
+      groups = group_by { |issue| issue.assignee.try(:login) }
+      groups.each_with_object(groups) do |(key, list), memo|
+        memo[key] = wrap(list)
+      end
+    end
+  end
+end

data/lib/hubkit/issue_paginator.rb

@@ -0,0 +1,23 @@
+module Hubkit
+  # Returns the list of issues for a repo, handling pagination for you
+  class IssuePaginator < Paginator
+    include Enumerable
+
+    # Initialize a new paginator for issues from the API
+    # @param [String] org the github organization which contains the repo for
+    #   which we'll gather issues
+    # @param [String] repo the github repo name for which we'll gather issues
+    # @param [optional String] state if missing or open, the paginator will
+    #   only have open issues returned. If 'all', the paginator will give you
+    #   open and closed issues.
+    def initialize(org:, repo:, state: 'open')
+      @org = org
+      @repo = repo
+      super() do |i|
+        Cooldowner.with_cooldown do
+          Github.issues.list(user: @org, repo: @repo, state: state, page: i)
+        end
+      end
+    end
+  end
+end

data/lib/hubkit/logger.rb

@@ -0,0 +1,62 @@
+require 'logger'
+
+module Hubkit
+  # The logger Hubkit uses for diagnostic info. If used in a Rails app and
+  # that Rails app already has a logger, it will use that same logger.
+  # Prepends [HUBKIT] to all log statements for easy filtering.
+  class Logger
+    # Write a debug level message to the log
+    # @param [String] msg the message to log
+    # @return [Boolean] true
+    def self.debug(msg)
+      inner_logger.debug('[HUBKIT] ' + msg)
+    end
+
+    # Write a info level message to the log
+    # @param [String] msg the message to log
+    # @return [Boolean] true
+    def self.info(msg)
+      inner_logger.info('[HUBKIT] ' + msg)
+    end
+
+    # Write a warning level message to the log
+    # @param [String] msg the message to log
+    # @return [Boolean] true
+    def self.warn(msg)
+      inner_logger.warn('[HUBKIT] ' + msg)
+    end
+
+    # Write a error level message to the log
+    # @param [String] msg the message to log
+    # @return [Boolean] true
+    def self.error(msg)
+      inner_logger.error('[HUBKIT] ' + msg)
+    end
+
+    # Write a fatal level message to the log
+    # @param [String] msg the message to log
+    # @return [Boolean] true
+    def self.fatal(msg)
+      inner_logger.fatal('[HUBKIT] ' + msg)
+    end
+
+    # Write a unknown level message to the log
+    # @param [String] msg the message to log
+    # @return [Boolean] true
+    def self.unknown(msg)
+      inner_logger.unknown('[HUBKIT] ' + msg)
+    end
+
+    # Return the ruby logger used by Hubkit
+    # @return [Logger] the logger. Rails is in use, will reuse the Rails
+    #   logger.
+    def self.inner_logger
+      @_inner_logger ||=
+        if Kernel.const_defined? 'Rails'
+          Rails.logger
+        else
+          ::Logger.new(STDERR)
+        end
+    end
+  end
+end

data/lib/hubkit/paginator.rb

@@ -0,0 +1,28 @@
+module Hubkit
+  # @abstract A class which implements an Enumerable which yields each resource returned
+  # by GitHub in turn, and handles the pagination for you (acts like a flat array,
+  # not an array of pages)
+  class Paginator
+    include Enumerable
+
+    # Construct a new paginator
+    # @yieldparam [Object] result each page of results
+    def initialize(&block)
+      @block = block
+    end
+
+    # Iterate through each page of the results and perform a block
+    # @yieldparam [Object] result each page of the
+    def each
+      i = 1
+      loop do
+        results = @block.call i
+        results.each do |result|
+          yield result
+        end
+        i += 1
+        break if results.length == 0
+      end
+    end
+  end
+end

data/lib/hubkit/repo.rb

@@ -0,0 +1,113 @@
+module Hubkit
+  # Represents one GitHub repo
+  # @attr [String] org the github organization containing the repo
+  # @attr [String] repo the github repo name
+  class Repo
+    attr_accessor :org, :repo
+
+    # List available repos
+    # @param [optional String] visibility if missing or 'all', retrieves all
+    #   repos. if 'public', only retrieves public repos
+    # @return [Enumerable] a list of Repo models accessible with the current
+    #   credentials
+    def self.list(visibility='all')
+      RepoCollection.new(
+        RepoPaginator
+          .new(visibility)
+          .map { |repo| { org: repo.owner.login, repo: repo.name } }
+          .map { |params| new(**params) }
+      )
+    end
+
+    # Initialize a Repo model from a github API payload
+    # @param [Github::Mash] gh the github API response
+    # @return [Repo] the matching Repo model
+    def self.from_gh(gh)
+      new(org: gh['owner']['login'], repo: gh.name)
+    end
+
+    # Initialize a Repo model from the name of the repo within the default
+    # organization
+    # @param [String] name the name of the repo
+    # @return [Repo] the matching Repo model
+    def self.from_name_with_default_org(name)
+      fail('Hubkit::Configuration.default_org is not set') if Hubkit::Configuration.default_org.nil?
+      return from_name(name) if name.include?('/')
+      from_name "#{Hubkit::Configuration.default_org}/#{name}"
+    end
+
+    # Initialize a Repo model from the organization and repo name
+    # @param [String] name the name of the organization/repo separated by a slash (/)
+    # @return [Repo] the matching Repo model
+    def self.from_name(name)
+      org, repo = name.split('/')
+      self.new(org: org, repo: repo)
+    end
+
+    # Construct a Repo model from the organization and repo name
+    # @param [String] org the name of the github organization
+    # @param [String] repo the name of the github repo
+    def initialize(org:, repo:)
+      @org = org
+      @repo = repo
+    end
+
+    # A list of issues for this Repo
+    # @param [Boolean] include_closed if true, will include closed issue. if
+    #   false or missing, the result will only include open issues
+    # @return [IssueCollection] the list of issues for the repo
+    def issues(include_closed = false)
+      issues_and_pulls(include_closed).true_issues
+    end
+
+    delegate :pulls, to: :issues_and_pulls
+
+    # A list of issues and pull requests for this Repo
+    # @param [Boolean] include_closed if true, will include closed issue. if
+    #   false or missing, the result will only include open issues
+    # @return [IssueCollection] the list of issues and pulls for the repo
+    def issues_and_pulls(include_closed = false)
+      @_issues_and_pulls ||= {}
+
+      @_issues_and_pulls[include_closed] ||=
+        IssueCollection.new(
+          paginator_for_status(include_closed).to_a.flat_map do |gh|
+            Issue.from_gh(org: @org, repo: @repo, gh: gh)
+          end,
+        )
+    end
+
+    # Get an IssuePaginator for a given open/closed issue status
+    # @param [Boolean] include_closed if true, paginator will return results
+    #   with closed issues. if false, closed issues will be excluded
+    # @return [IssuePaginator] the issue paginator for this status and repo
+    def paginator_for_status(include_closed)
+      state_flag = include_closed ? 'all' : 'open'
+
+      IssuePaginator.new(
+        org: @org,
+        repo: @repo,
+        state: state_flag,
+      )
+    end
+
+    # Get an array of label strings which are available on this repo
+    # @return [Enumerable] a list of strings which are the names of labels
+    #   available on this repo
+    def labels
+      @_labels ||=
+        Github
+        .issues.labels.list(@org, @repo, per_page: 100)
+        .map(&:name)
+        .map(&:downcase)
+        .uniq
+    end
+
+    # Return a human readable description of the Repo model
+    # @return [String] the human readable representation of the Repo model
+    #   for the console
+    def inspect
+      "#<Hubkit::Repo:0x#{(object_id << 1).to_s(16)} #{@org}/#{@repo}>"
+    end
+  end
+end

data/lib/hubkit/repo_collection.rb

@@ -0,0 +1,14 @@
+module Hubkit
+  # A collection of Repos with chainable filters
+  class RepoCollection < ChainableCollection
+    scope :organization do |x|
+      @inner.select do |repo|
+        repo['owner']['login'] == x
+      end
+    end
+
+    scope :fork do
+      wrap(@inner.select { |repo| repo['fork'] })
+    end
+  end
+end

data/lib/hubkit/repo_paginator.rb

@@ -0,0 +1,17 @@
+module Hubkit
+  # Retrieves all visible repos in one flat array, handling GitHub pagination
+  class RepoPaginator < Paginator
+    include Enumerable
+
+    # Construct a new repo paginator
+    # @param [optional String] visibility if missing or 'all', retrieves all
+    #   repos. if 'public', only retrieves public repos
+    def initialize(visibility='all')
+      super() do |i|
+        Cooldowner.with_cooldown do
+          Hubkit.client.repos.list(visibility: visibility, page: i)
+        end
+      end
+    end
+  end
+end

data/lib/hubkit/version.rb

@@ -0,0 +1,4 @@
+module Hubkit
+  # The current version of the Hubkit library
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: hubkit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Robert Prehn
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-06-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: github_api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.16.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.16.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !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'
+description: |2
+      Hubkit provides methods for querying the github API at a higher level than
+      making individual API calls. Think of it like an ORM for the github API.
+email:
+- robert@revelry.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- hubkit.gemspec
+- lib/hubkit.rb
+- lib/hubkit/chainable_collection.rb
+- lib/hubkit/configuration.rb
+- lib/hubkit/cooldowner.rb
+- lib/hubkit/event_collection.rb
+- lib/hubkit/event_paginator.rb
+- lib/hubkit/issue.rb
+- lib/hubkit/issue_collection.rb
+- lib/hubkit/issue_paginator.rb
+- lib/hubkit/logger.rb
+- lib/hubkit/paginator.rb
+- lib/hubkit/repo.rb
+- lib/hubkit/repo_collection.rb
+- lib/hubkit/repo_paginator.rb
+- lib/hubkit/version.rb
+homepage: https://github.com/prehnRA/hubkit
+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: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Higher level abstractions for querying the github API
+test_files: []
+has_rdoc: