rescuetime 0.3.2 → 1.0.2

data/CODE_OF_CONDUCT.md

@@ -1,13 +1,74 @@
 # Contributor Code of Conduct
 
-As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+## Our Pledge
 
-We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
+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.
 
-Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+## Our Standards
 
-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. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+Examples of behavior that contributes to creating a positive environment
+include:
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+* 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
 
-This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)
+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 maintainer at lee@leesharma.com. 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/Gemfile

@@ -1,10 +1,8 @@
 source 'https://rubygems.org'
 
-gem 'rubocop', require: false
-
 group :test do
   gem 'codeclimate-test-reporter', '~> 0.4.7'
-  gem 'simplecov', '~> 0.9.2'
+  gem 'simplecov', '~> 0.11.2'
 end
 
 # Specify your gem's dependencies in rescuetime.gemspec

data/README.md

@@ -1,10 +1,9 @@
 rescuetime
 ==========
 
-[![Quality](http://img.shields.io/codeclimate/github/leesharma/rescuetime.svg?style=flat-square)](https://codeclimate.com/github/leesharma/rescuetime)
-[![Coverage](http://img.shields.io/codeclimate/coverage/github/leesharma/rescuetime.svg?style=flat-square)](https://codeclimate.com/github/leesharma/rescuetime)
+[![Maintainability](https://img.shields.io/codeclimate/maintainability/leesharma/rescuetime.svg?style=flat-square)](https://codeclimate.com/github/leesharma/rescuetime)
+[![Coverage](https://img.shields.io/codeclimate/coverage/leesharma/rescuetime.svg?style=flat-square)](https://codeclimate.com/github/leesharma/rescuetime)
 [![Build](https://img.shields.io/travis/leesharma/rescuetime.svg?style=flat-square)](https://travis-ci.org/leesharma/rescuetime)
-[![Dependencies](https://img.shields.io/gemnasium/leesharma/rescuetime.svg?style=flat-square)](https://gemnasium.com/leesharma/rescuetime)
 
 [![Downloads](https://img.shields.io/gem/dt/rescuetime.svg?style=flat-square)](https://rubygems.org/gems/rescuetime)
 [![Release](https://img.shields.io/github/release/leesharma/rescuetime.svg?style=flat-square)](https://github.com/leesharma/rescuetime/releases/)
@@ -21,11 +20,13 @@ For more information about RescueTime, visit [the RescueTime homepage](https://w
 * [Usage](#usage)
    * [Prerequisites](#prerequisites)
    * [In a Nutshell](#in-a-nutshell) (skip to here if you want to see the syntax)
+   * [Custom Report Formatters](#custom-report-formatters)
    * [Finding Answers (Documentation)](#finding-answers-documentation)
    * [Defaults](#defaults)
    * [Rescuetime Exceptions](#rescuetime-exceptions)
 * [Development](https://github.com/leesharma/rescuetime/wiki/Development) ([section](#development))
 * [Contributing](CONTRIBUTING.md) ([section](#contributing))
+   * [TODO](#todo)
 
 #### Useful Links
 * [RDoc](http://www.rubydoc.info/gems/rescuetime)
@@ -51,7 +52,7 @@ Or install it yourself as:
 
 ### Prerequisites
 
-Ensure that you are using a [supported ruby version](https://github.com/leesharma/rescuetime/wiki/Supported-Rubies) for your project. 
+Ensure that you are using a [supported ruby version](https://github.com/leesharma/rescuetime/wiki/Supported-Rubies) for your project.
 
 In order to use access your RescueTime data, you will need an API key. If you do not already have a key, visit the [API key management page](https://www.rescuetime.com/anapi/manage).
 
@@ -66,7 +67,7 @@ require 'rescuetime'
 
 # Rescuetime uses lazy evaluation, so until you either manipulate the collection
 # or explicitly call for it (with #all), it will remain in the Rescuetime::Collection
-# format. 
+# format.
 @client.overview.class      #=> Rescuetime::Collection
 @client.overview.all.class  #=> Array
 @client.overview.map {...}  #=> Array
@@ -89,9 +90,9 @@ require 'rescuetime'
 #   - Object#strftime
 @client.overview                      # Fetches results from today
 @client.overview.date('2014-12-31')   # Fetches results from Dec 31, 2014.
-@client.overview.from('2015-01-01').to('2015-02-01')         
-@client.overview.from('2015-04-01')            
-       
+@client.overview.from('2015-01-01').to('2015-02-01')
+@client.overview.from('2015-04-01')
+
 
 ##
 # Report Order (:order_by)
@@ -99,7 +100,7 @@ require 'rescuetime'
 # Defaults:
 #   Efficiency defaults to chronological order; everything else defaults to "rank" order
 #
-# You can order_by: 
+# You can order_by:
 #   :rank, :time, or :member (note: efficiency can't be sorted by :rank)
 #
 # When ordering by time, default interval is 1 hour.
@@ -107,15 +108,15 @@ require 'rescuetime'
 #   :minute (5-minute chunks), :hour, :day, :week, :month
 @client.efficiency    # Defaults to :time
 @client.productivity  # Defaults to :rank
-                                          
-@client.productivity.order_by(:rank)       
-@client.productivity.order_by(:time)      
-@client.productivity.order_by(:member)    
-                                          
+
+@client.productivity.order_by(:rank)
+@client.productivity.order_by(:time)
+@client.productivity.order_by(:member)
+
 @client.productivity.order_by(:time)  # Defaults to :hour
-@client.productivity.order_by(:time, interval: :minute)     
-@client.productivity.order_by(:time, interval: :hour)       
-@client.productivity.order_by(:time, interval: :day)        
+@client.productivity.order_by(:time, interval: :minute)
+@client.productivity.order_by(:time, interval: :hour)
+@client.productivity.order_by(:time, interval: :day)
 @client.productivity.order_by(:time, interval: :week)
 @client.productivity.order_by(:time, interval: :month)
 
@@ -131,10 +132,10 @@ require 'rescuetime'
 #   Try the query sans document for a list of valid options
 #
 # Names must be exact matches.
-@client.activities.where(name: 'github.com')    
-@client.categories.where(name: 'Intelligence')  
-@client.overview.where(name: 'Utilities')       
-@client.activities.where(name: 'github.com', document: 'vcr/vcr')                   
+@client.activities.where(name: 'github.com')
+@client.categories.where(name: 'Intelligence')
+@client.overview.where(name: 'Utilities')
+@client.activities.where(name: 'github.com', document: 'vcr/vcr')
 
 ##
 # Formatting options (:csv, :array)
@@ -144,9 +145,113 @@ require 'rescuetime'
 @client.efficiency.format(:array)   # Returns Array<Hash>
 ```
 
+### Custom Report Formatters
+
+*Feature available in v0.4.0 and later*
+
+Rescuetime ships with two report formats: CSV and Array. If you would like your
+report in a different format, don't worry–it's easy to add a custom formatter.
+
+Three things are required to add a custom formatter:
+
+1. [Write a class](#writing-a-formatter) within the module
+   `Rescuetime::Formatters` that inherits from `Rescuetime::Formatters::BaseFormatter`
+   or one of its descendants
+2. Define the class methods `.name` and `.format`
+4. [Register your formatters](#registering-your-formatters) using `Rescuetime.configure`
+
+#### Writing a Formatter
+
+First, the formatters themselves. Here is a basic formatter:
+
+```ruby
+# config/formatters/nil_formatter.rb
+module Rescuetime::Formatters
+  # Turns a productivity report into nothing useful.
+  class NilFormatter < BaseFormatter
+    # @return [String]  name of this report format
+    def self.name
+      'nil'
+    end
+
+    # @param  [CSV] _report  the raw CSV report from Rescuetime
+    # @return [nil]          the formatted output (in this case, nil)
+    def self.format(_report)
+      nil
+    end
+  end
+end
+```
+
+You can even inherit from an existing formatter:
+
+```ruby
+# config/formatters/shouty_array_formatter.rb
+module Rescuetime::Formatters
+  # Formats a rescuetime report as an array of hashes, except shouting.
+  class ShoutyArrayFormatter < ArrayFormatter
+    # @return [String]  name of this report format
+    def self.name
+      'shouty_array'
+    end
+
+    # @param  [CSV]         report  the raw CSV report from Rescuetime
+    # @return [Array<Hash>]         the formatted output (in this case, a shouty
+    #                               array of hashes)
+    def self.format(report)
+      array = super(report)
+      array.map do |hash|
+        terms = hash.map { |key, value| [key.to_s.upcase, value.to_s.upcase] }
+        Hash[terms]
+      end
+    end
+  end
+end
+```
+
+#### Registering your Formatters
+
+Before setting your report format, add the path to your formatter(s) to the
+Rescuetime configuration using the `Rescuetime.configure` method. You will be
+able to set, append to, or manipulate the `formatter_paths` setting.
+
+```ruby
+Rescuetime.configure do |config|
+  path = File.expand_path('../my_custom_formatter.rb', __FILE__)
+  config.formatter_paths = [path]
+end
+```
+
+Now Rescuetime will look for the `my_custom_formatter.rb` file. Multiple paths
+may be added as well.
+
+```ruby
+Rescuetime.configure do |config|
+  config.formatter_paths = [
+    'config/formatters/*_formatter.rb',
+    'lib/formatters/**/*_formatter.rb',
+  ]
+end
+```
+
+##### Rails Example
+
+For example, in a Rails app, you could add the configuration file to `config/initializers`:
+
+```ruby
+# config/initializers/rescuetime.rb
+Rescuetime.configure do |config|
+  path = File.expand_path('../../formatters/*_formatter.rb', __FILE__)
+  config.formatter_paths += [path]
+end
+```
+
+Rails can now find any formatters ending in `_formatter.rb` in the folder `config/formatters`
+(ex. `config/formatters/xml_formatter.rb`).
+
 ### Finding Answers (Documentation)
 
-For more details, please see [official gem documentation](http://www.rubydoc.info/gems/rescuetime) or [read the wiki](https://github.com/leesharma/rescuetime/wiki). 
+For more details, please see [official gem documentation](http://www.rubydoc.info/gems/rescuetime) or [read the wiki](https://github.com/leesharma/rescuetime/wiki).
 
 ### Defaults
 
@@ -162,27 +267,32 @@ The `Rescuetime::Client#activities` action has the following defaults:
 
 ### Rescuetime Exceptions
 
-There are a number of exceptions that extend from the custom Rescuetime::Error class:
+*Note: In v0.4.0, custom exceptions were moved from the base `Rescuetime`
+namespace to the `Rescuetime::Errors` namespace. For example, in v0.3.3,
+a bad request was represented by `Rescuetime::BadRequest`. In >= v0.4.0,
+it is represented by `Rescuetime::Errors::BadRequest`.*
 
-* **Rescuetime::MissingCredentialsError** is raised when a request is attempted by a client with no credentials. Try setting credentials with `@client.api_key = <YOUR_API_KEY>`.
-* **Rescuetime::InvalidCredentialsError** is raised when a request is attempted by a client with invalid credentials. Double-check your API key and fix your client with `@client.api_key = <VALID_API_KEY>`.
-* **Rescuetime::InvalidQueryError** is raised if you enter an invalid value for any of the RescueTime query methods (or if the server returns a bad query error)
-* **Rescuetime::InvalidFormatError** is raised if you pass a disallowed format to the client
+There are a number of exceptions that extend from the `Rescuetime::Errors::Error` class:
+
+* **`Rescuetime::Errors::MissingCredentialsError`** is raised when a request is attempted by a client with no credentials. Try setting credentials with `@client.api_key = <YOUR_API_KEY>`.
+* **`Rescuetime::Errors::InvalidCredentialsError`** is raised when a request is attempted by a client with invalid credentials. Double-check your API key and fix your client with `@client.api_key = <VALID_API_KEY>`.
+* **`Rescuetime::Errors::InvalidQueryError`** is raised if you enter an invalid value for any of the RescueTime query methods (or if the server returns a bad query error)
+* **`Rescuetime::Errors::InvalidFormatError`** is raised if you pass a disallowed format to the client
 * HTTP Response Errors:
-  * **4xx => Rescuetime:: ClientError**
-  * 400 => Rescuetime::BadRequest
-  * 401 => Rescuetime::Unauthorized
-  * 403 => Rescuetime::Forbidden
-  * 404 => Rescuetime::NotFound
-  * 406 => Rescuetime::NotAcceptable
-  * 422 => Rescuetime::UnprocessableEntity
-  * 429 => Rescuetime::TooManyRequests
-  * **5xx => Rescuetime:: ServerError**
-  * 500 => Rescuetime::InternalServerError
-  * 501 => Rescuetime::NotImplemented
-  * 502 => Rescuetime::BadGateway
-  * 503 => Rescuetime::ServiceUnavailable
-  * 504 => Rescuetime::GatewayTimeout
+    * **4xx => `Rescuetime::Errors::ClientError`**
+    * 400 => `Rescuetime::Errors::BadRequest`
+    * 401 => `Rescuetime::Errors::Unauthorized`
+    * 403 => `Rescuetime::Errors::Forbidden`
+    * 404 => `Rescuetime::Errors::NotFound`
+    * 406 => `Rescuetime::Errors::NotAcceptable`
+    * 422 => `Rescuetime::Errors::UnprocessableEntity`
+    * 429 => `Rescuetime::Errors::TooManyRequests`
+    * **5xx => `Rescuetime::Errors::ServerError`**
+    * 500 => `Rescuetime::Errors::InternalServerError`
+    * 501 => `Rescuetime::Errors::NotImplemented`
+    * 502 => `Rescuetime::Errors::BadGateway`
+    * 503 => `Rescuetime::Errors::ServiceUnavailable`
+    * 504 => `Rescuetime::Errors::GatewayTimeout`
 
 ## Development
 
@@ -191,3 +301,36 @@ See the [development page](https://github.com/leesharma/rescuetime/wiki/Developm
 ## Contributing
 
 See the [contributing page](CONTRIBUTING.md).
+
+### TODO
+
+The eventual goal of this gem is full coverage of all Rescuetime APIs.
+
+Associated issues from our issue tracker are linked when applicable. If you are interested in contributing, please feel free to work on any of these issues! If there is a feature you want that's not on the TODO list, open an issue and we can discuss it.
+
+- [x] Minimum viable functionality (in [v0.1.0])
+- [x] Add support for major query params in Data Analytic API (in [v0.2.0])
+- [x] Lazy query evaluation and method chaining (in [v0.3.0], [v0.3.1], [v0.3.2], [v0.3.3])
+- [x] Add custom report formatters (in [v0.4.0])
+- [ ] Add full coverage of Data Analytics API
+  - [ ] Restrict results by group ([#14])
+  - [ ] Restrict results by person
+- [ ] Add support for "Daily Summary API" ([#28])
+- [ ] Add support for "Alerts Feed API"
+- [ ] Add support for "Daily Highlights Feed API"
+- [ ] Add support for "Daily Highlights POST API"
+- [ ] Add OAuth2 support
+
+For details about completed items, please see [the release page][releases].
+
+[#14]: https://github.com/leesharma/rescuetime/issues/14
+[#28]: https://github.com/leesharma/rescuetime/issues/28
+
+[v0.1.0]:https://github.com/leesharma/rescuetime/releases/tag/v0.1.0
+[v0.2.0]:https://github.com/leesharma/rescuetime/releases/tag/v0.2.0
+[v0.3.0]:https://github.com/leesharma/rescuetime/releases/tag/v0.3.0
+[v0.3.1]:https://github.com/leesharma/rescuetime/releases/tag/v0.3.1
+[v0.3.2]:https://github.com/leesharma/rescuetime/releases/tag/v0.3.2
+[v0.3.3]:https://github.com/leesharma/rescuetime/releases/tag/v0.3.3
+[v0.4.0]:https://github.com/leesharma/rescuetime/releases/tag/v0.4.0
+[releases]:https://github.com/leesharma/rescuetime/releases

data/Rakefile

@@ -11,7 +11,7 @@ defaults = [:spec]
 begin
   require 'rubocop/rake_task'
   RuboCop::RakeTask.new(:rubocop)
-  # defaults << :rubocop
+  defaults << :rubocop
 rescue LoadError
   puts 'Rubocop is not installed; please install it for code quality checks.'
 end

data/lib/rescuetime.rb

@@ -1,10 +1,75 @@
+# frozen_string_literal: true
+
 require 'rescuetime/version'
+require 'rescuetime/configuration'
 require 'rescuetime/client'
 require 'rescuetime/errors'
 
-# lib/rescuetime.rb
+# Wrapper module for rescuetime gem
+#
+# @since v0.1.0
 module Rescuetime
-  # Wrapper module for rescuetime gem
+  # class << self
+  #   attr_writer :configuration
+  # end
+
+  # Passes a block to the Rescuetime configuration, allowing configuration
+  # options to be set.
+  #
+  # @example
+  #   # In an initializer or before any report formatters are called:
+  #   Rescuetime.configure do |config|
+  #     config.formatter_paths += ['path/to/local/formatters/*_formatter.rb']
+  #   end
+  #
+  #   # Let's say that directory contains the valid formatters pdf_formatter.rb
+  #   # and json_formatter.rb
+  #   report_formatters = Rescuetime::ReportFormatters.new
+  #   puts report_formatters.all
+  #   #=> ["array", "csv", "pdf", "json"]
+  #
+  # @see Rescuetime.configuration
+  # @see Rescuetime::Configuration
+  # @since v0.4.0
+  def self.configure
+    yield(configuration)
+  end
+
+  # Returns either the current configuration (if set) or initializes a new
+  # default configuration.
+  #
+  # @example
+  #   Rescuetime.configuration.formatter_paths
+  #   #=> []
+  #
+  #   Rescuetime.configure do |config|
+  #     config.formatter_paths += ['formatters/*.rb']
+  #   end
+  #   Rescuetime.configuration.formatter_paths
+  #   #=> ["formatters/*.rb"]
+  #
+  # @see Rescuetime::Configuration
+  # @return [Rescuetime::Configuration]  the current Rescuetime configuration
+  # @since v0.4.0
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Resets the configuration back to the initial state. Mainly useful for
+  # resetting the class after testing, making specs order-independent.
+  #
+  # @example
+  #   before :each do
+  #     Rescuetime.configure { |c| c.formatter_paths += ['formatters/*.rb'] }
+  #   end
+  #
+  #   after :each do
+  #     Rescuetime.reset
+  #   end
   #
-  # @since v0.1.0
+  # @see Rescuetime::Configuration#initialize
+  # @since v0.4.0
+  def self.reset
+    @configuration = Configuration.new
+  end
 end