Merge pull request #26 from leesharma/v0.2.1

V0.3.0

.travis.yml

@@ -2,7 +2,6 @@ cache: bundler
 
 language: ruby
 rvm:
-  - 1.9.3
   - 2.0.0
   - 2.1
   - 2.2

CONTRIBUTING.md

@@ -29,20 +29,21 @@ You should be able to run the test specs now:
 bundle exec rake
 ```
 
-Some great ways to contribute include:
-- fixing [bugs](https://github.com/leesharma/rescuetime/issues?q=is%3Aopen+is%3Aissue+-label%3A%22in+progress%22+label%3Abug)
-- adding [features listed in our current milestone](https://github.com/leesharma/rescuetime/issues?q=is%3Aopen+is%3Aissue+-label%3A%22in+progress%22) (filter by milestone)
-- adding/improving documentation, comments, etc.
-- refactoring existing code
-
-Check our [issue tracker](https://github.com/leesharma/rescuetime/issues) for more ideas.
+This is a very small project, so if you are interested in contributing, it will be easiest if you contact me first.
 
 ## Standards
 
 rescuetime uses RSpec for testing along with VCR and WebMock for mocking HTTP responses. Any pull request that includes changes to the code (ie. everything but comments and documentation) requires complete test coverage.
 
 Be careful not to commit sensitive information (API keys, OAuth credentials, etc.) to public repositories!
 
+### Comment Tags
+
+* TODO
+* FIXME
+* OPTIMIZE
+* REVIEW
+
 ## Questions
 
-Have any questions? Feel free to send me (@leesharma) a message!
+Have any questions? Post on the github repo at leesharma/rescuetime.

README.md

@@ -20,7 +20,8 @@ For more information about RescueTime, visit [the RescueTime homepage](https://w
 * [Installation](#installation)
 * [Usage](#usage)
    * [Prerequisites](#prerequisites)
-   * [Getting Started](#getting-started)
+   * [In a Nutshell](#in-a-nutshell) (skip to here if you want to see the syntax)
+   * [Finding Answers (Documentation)](#finding-answers-documentation)
    * [Defaults](#defaults)
    * [Rescuetime Exceptions](#rescuetime-exceptions)
 * [Development](https://github.com/leesharma/rescuetime/wiki/Development) ([section](#development))
@@ -54,9 +55,7 @@ Ensure that you are using a [supported ruby version](https://github.com/leesharm
 
 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).
 
-### Getting Started
-
-Using the rescuetime gem is simple. Here is some example code using the rescuetime gem (a full feature list can be found [here](https://github.com/leesharma/rescuetime/wiki#full-specs):
+### In a Nutshell
 
 ```ruby
 require 'rescuetime'
@@ -65,19 +64,88 @@ require 'rescuetime'
 @client.api_key?            #=> true
 @client.valid_credentials?  #=> true
 
-@client.activities          # Returns a list of activities, ordered by "rank"
-@client.productivity        # Returns a productivity report
-@client.efficiency          # Returns an efficiency report, ordered by "time"
-
-@client.activities.class    # => Array
-@client.activities[0].class # => Hash
-
-@client.efficiency( from: '2015-03-20',     # returns weekly efficiency report between March 20th and 
-                    to: '2015-04-20' ,      #   April 20th of 2015 by member in csv format
-                    interval: 'week', 
-                    format: 'csv' )
+# 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. 
+@client.overview.class      #=> Rescuetime::Collection
+@client.overview.all.class  #=> Array
+@client.overview.map {...}  #=> Array
+
+@client.overview      # Returns an overview report, defaulting to "rank" order
+@client.categories    # Returns a catigorical report, defaulting to "rank" order
+@client.activities    # Returns a list of activities, defaulting to "rank" order
+@client.productivity  # Returns a productivity report, defaulting to "rank" order
+@client.efficiency    # Returns an efficiency report, defaulting to "time order"
+
+##
+# Date Range (:date, :frome, :to)
+# -------------------------------
+# Defaults:
+#   If nothing is provided, defaults to current day (since 00:00)
+#   If :from is provided, defaults :to to current day
+#
+# Valid date formats:
+#   - "YYYY-MM-DD"    - "MM-DD-YYYY"    - "DD/MM"
+#   - 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')            
+
+
+##
+# Report Order (:order_by)
+# ------------------------
+# Defaults:
+#   Efficiency defaults to chronological order; everything else defaults to "rank" order
+#
+# 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.
+# Options include:
+#   :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(: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: :week)
+@client.productivity.order_by(:time, interval: :month)
+
+##
+# Name Restrictions (:where)
+# --------------------------
+# Fetches results where name is an exact match
+# The following reports can be limited by name:
+#   :activities, :categories, :overview
+#
+# For activities, you can also limit by specific document title
+#   (ex. document 'rails/rails' for activity 'github.com')
+#   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')                   
+
+##
+# Formatting options (:csv, :array)
+# ---------------------------------
+@client.efficiency                  # Default return type is Array<Hash>
+@client.efficiency.format(:cvs)     # Returns a CSV
+@client.efficiency.format(:array)   # Returns Array<Hash>
 ```
 
+### Finding Answers (Documentation)
+
 For more details, please see [official gem documentation](http://www.rubydoc.info/gems/rescuetime/0.1.0) or [read the wiki](https://github.com/leesharma/rescuetime/wiki). 
 
 ### Defaults
@@ -86,19 +154,35 @@ The `Rescuetime::Client#activities` action has the following defaults:
 
 ```ruby
 
-{ by:               'rank'
-  time_interval:    'hour'
-  date:             <TODAY>
-  detail:           'activity' }
+{ order_by:         'rank'
+  interval:         'hour'
+  date:             <TODAY> }
 
 ```
 
 ### Rescuetime Exceptions
 
 There are a number of exceptions that extend from the custom Rescuetime::Error class:
 
-* **Rescuetime::MissingCredentials** is raised when a request is attempted by a client with no credentials. Try setting credentials with `@client.api_key=<YOUR_API_KEY>`.
-* **Rescuetime::InvalidCredentials** 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::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
+* 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
 
 ## Development
 

Rakefile

@@ -8,4 +8,4 @@ RSpec::Core::RakeTask.new(:spec)
 task test: :spec
 
 desc 'Default: run specs'
-task default: :spec
+task default: :spec

lib/rescuetime.rb

@@ -2,6 +2,7 @@
 require 'rescuetime/client'
 require 'rescuetime/errors'
 
+# lib/rescuetime.rb
 module Rescuetime
   # Wrapper module for rescuetime gem
   #