rescuetime 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d14aafe98892e8e11f57043050fe2906c6f73f45
-  data.tar.gz: a8d7bc8a5acd04b0352341173835133e10ef06fd
+  metadata.gz: 6464e2b8b391cfa2b334288ba6cdbd81fe7728f6
+  data.tar.gz: e293998bd6552509d6225422b1a7f029a26dcde3
 SHA512:
-  metadata.gz: fa1aea8ef22994a34faf16834107719fc69373a0ae4f09e78ac86871fcf05527e92dad6d9ee106c3de6bf5addbb717066d4fd97ef4e3be394eb5d1cc140041ed
-  data.tar.gz: 2a8ba29a4bbdd16d967b8f2d6fc8737fd6cc30a7f0776357949817a66c6fcc89ca1579b8292b2169ad11313b75b1e4e32038fc8ff50d5fc8487f6b20b39c10f2
+  metadata.gz: 4e022e5eefb8a858051f8c5264d394562ba6939381beb5b9072807f2dad2a70f9d8047ada933a2be9172ba050ed5b71ed41e51934e1b2a8ade83bd67d7a645c2
+  data.tar.gz: 8c09915abb016f0680d9b48c1f45362ccf6312fc970f1e58d38feeb25e15afda6cfeba1d5f18a877712ac7b29bce2e65f39cdf14ebea57caf79f26fbcdc5df33

data/.rubocop.yml

@@ -0,0 +1 @@
+inherit_from: .rubocop_todo.yml

data/.rubocop_todo.yml

@@ -0,0 +1,80 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2016-05-22 00:42:00 -0400 using RuboCop version 0.40.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+Lint/AmbiguousOperator:
+  Exclude:
+    - 'lib/rescuetime/collection.rb'
+
+# Offense count: 1
+# Configuration parameters: CountComments.
+Metrics/MethodLength:
+  Max: 13
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Performance/StringReplacement:
+  Exclude:
+    - 'lib/rescuetime/date_parser.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+# SupportedStyles: always, conditionals
+Style/AndOr:
+  Exclude:
+    - 'lib/rescuetime/query_buildable.rb'
+
+# Offense count: 5
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles, IndentationWidth.
+# SupportedStyles: aligned, indented
+Style/MultilineMethodCallIndentation:
+  Enabled: false
+
+# Offense count: 9
+# Cop supports --auto-correct.
+Style/MutableConstant:
+  Exclude:
+    - 'lib/rescuetime/collection.rb'
+    - 'lib/rescuetime/date_parser.rb'
+    - 'lib/rescuetime/errors.rb'
+    - 'lib/rescuetime/query_buildable.rb'
+    - 'lib/rescuetime/requester.rb'
+    - 'lib/rescuetime/version.rb'
+    - 'spec/sample_secret.rb'
+    - 'spec/secret.rb'
+
+# Offense count: 3
+# Cop supports --auto-correct.
+Style/NestedParenthesizedCalls:
+  Exclude:
+    - 'spec/rescuetime/query_buildable_spec.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Style/ParallelAssignment:
+  Exclude:
+    - 'spec/rescuetime/query_buildable_spec.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Style/RedundantSelf:
+  Exclude:
+    - 'lib/rescuetime/query_buildable.rb'
+
+# Offense count: 10
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+# SupportedStyles: only_raise, only_fail, semantic
+Style/SignalException:
+  Exclude:
+    - 'lib/rescuetime/collection.rb'
+    - 'lib/rescuetime/date_parser.rb'
+    - 'lib/rescuetime/query_buildable.rb'
+    - 'lib/rescuetime/requester.rb'

data/Gemfile

@@ -1,5 +1,7 @@
 source 'https://rubygems.org'
 
+gem 'rubocop', require: false
+
 group :test do
   gem 'codeclimate-test-reporter', '~> 0.4.7'
   gem 'simplecov', '~> 0.9.2'

data/README.md

@@ -146,7 +146,7 @@ require 'rescuetime'
 
 ### 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). 
+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
 
@@ -164,7 +164,7 @@ The `Rescuetime::Client#activities` action has the following defaults:
 
 There are a number of exceptions that extend from the custom Rescuetime::Error class:
 
-* * **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::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

data/Rakefile

@@ -3,9 +3,18 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
-desc 'Run all the tests in spec'
 RSpec::Core::RakeTask.new(:spec)
 task test: :spec
 
-desc 'Default: run specs'
-task default: :spec
+defaults = [:spec]
+
+begin
+  require 'rubocop/rake_task'
+  RuboCop::RakeTask.new(:rubocop)
+  # defaults << :rubocop
+rescue LoadError
+  puts 'Rubocop is not installed; please install it for code quality checks.'
+end
+
+desc "Run default actions: #{defaults}"
+task default: defaults

data/lib/rescuetime/client.rb

@@ -14,31 +14,101 @@ module Rescuetime
   class Client
     include QueryBuildable
 
-    # @!attribute [rw] api_key
-    # @since v0.1.0
+    # Represents the client's Rescuetime API key, required for successful
+    # requests
+    #
+    # @return [String, nil]    Rescuetime API key
     attr_accessor :api_key
 
-    # @since v0.1.0
-    def initialize(key = nil, **opts)
-      @api_key    = key || opts[:api_key]
+    # Creates a new Rescuetime client. The API key can be passed as either a
+    # parameter or option (with "key" taking priority over ":api_key")
+    #
+    # @example Basic Use
+    #   Rescuetime::Client.new
+    #   # => #<Rescuetime::Client:0x007f938489b6c8 @api_key=nil>
+    #
+    # @example Setting the API Key
+    #   Rescuetime::Client.new
+    #   # => #<Rescuetime::Client:0x007f938489b6c8 @api_key=nil>
+    #
+    #   Rescuetime::Client.new('12345')
+    #   # => #<Rescuetime::Client:0x007f938489b6c8 @api_key="12345">
+    #
+    #   Rescuetime::Client.new(api_key: 12345')
+    #   # => #<Rescuetime::Client:0x007f938489b6c8 @api_key="12345">
+    #
+    #   Rescuetime::Client.new('123', api_key: '456')
+    #   # => #<Rescuetime::Client:0x007f938489b6c8 @api_key="123">
+    #
+    # @param  [String, nil] key      API key
+    # @param  [String]      api_key  Rescuetime API key
+    # @return [Rescuetime::Client]
+    def initialize(key = nil, api_key: nil)
+      @api_key = key || api_key
     end
 
-    # @since v0.1.0
+    # Returns true if the API key is present.
+    #
+    # @example Basic Use
+    #   client = Rescuetime::Client.new
+    #   client.api_key?
+    #   # => false
+    #
+    #   client.api_key = ''
+    #   client.api_key?
+    #   # => false
+    #
+    #   client.api_key = '12345'
+    #   client.api_key?
+    #   # => true
+    #
+    # @return [Boolean]
     def api_key?
-      !!@api_key && !@api_key.empty?
+      present? api_key
     end
 
-    # @since v0.2.0
+    # Returns true if the provided api key is valid. Performs a request to the
+    # Rescuetime API.
+    #
+    # @example Basic Use
+    #   # Assuming that INVALID_KEY is an invalid Rescuetime API key
+    #   # and VALID_KEY is a valid one
+    #
+    #   client = Rescuetime::Client
+    #   client.valid_credentials?
+    #   # => false
+    #
+    #   client.api_key = INVALID_KEY
+    #   client.valid_credentials? # Performs a request to the Rescuetime API
+    #   # => false
+    #
+    #   client.api_key = VALID_KEY
+    #   client.valid_credentials? # Performs a request to the Rescuetime API
+    #   # => true
+    #
+    # @return [Boolean]
     def valid_credentials?
       return false unless api_key?
-      !!activities.all rescue false
+      !activities.all.nil?
+    rescue Rescuetime::InvalidCredentialsError
+      false
     end
 
     private
 
-    # @since v0.3.0
+    # Returns true if the project is present and non-blank
+    #
+    # @param  [#emtpy?] obj
+    # @return [Boolean]
+    # @since  v0.3.2
+    def present?(obj)
+      blank = obj.respond_to?(:empty?) ? obj.empty? : obj.nil?
+      !blank
+    end
+
+    # @return [Hash]
     def state
-      { key: @api_key }
+      { key: api_key }
     end
   end
 end

data/lib/rescuetime/collection.rb

@@ -1,46 +1,79 @@
 require 'rescuetime/query_buildable'
 
 module Rescuetime
+  # Represents a potential rescuetime collection. It holds the query information
+  # and performs the query lazily, when #all or an Enumerable method is called.
   class Collection
     include QueryBuildable
     include Enumerable
 
+    # Rescuetime Analytics API endpoint
     HOST = 'https://www.rescuetime.com/anapi/data'
 
+    # Returns a new Rescuetime collection. Default format is array.
+    #
+    # @param  [Array<Hash>]            terms  a list of parameter hashes
+    # @return [Rescuetime::Collection]        a new Rescuetime collection
     def initialize(*terms)
       @params = terms.reduce({}, :merge)
       @format = :array
     end
 
+    # Appends new terms onto the Rescuetime collection. In the case of duplicate
+    # keys, the later keys overwrite the former keys.
+    #
+    # @param  [Hash] terms  new terms to add to collection params
+    # @return [Hash]        collection params with terms merged in
     def <<(terms)
-      @params.merge! terms
+      @params = params.merge terms
     end
 
+    # Performs the rescuetime query and returns an array or csv response.
+    #
+    # @return [Array, CSV]
+    #
+    # @see Rescuetime::Requester#get
     def all
-      parse_response Requester.get(HOST, @params).body
+      parse_response Requester.get(HOST, params).body
     end
 
+    # Enumerates over the collection of Rescuetime report records. Performs
+    # the query.
+    #
+    # @return [Array, CSV]
+    #
+    # @see #all
+    # @see http://ruby-doc.org/core/Enumerable.html Enumerable
     def each(&block)
       all.each &block
     end
 
-    # TODO: Chainable to client
+    # @param  [#to_s] format  desired report format (one of 'array' or 'csv')
+    # @return [Rescuetime::Collection]
+    #
+    # @todo: make chainable to the client
     def format(format)
-      fail InvalidFormatError unless %w(array csv).include? format.to_s
-      @format = format.to_sym
+      format = format.to_s
+      fail InvalidFormatError unless %w(array csv).include? format
+
+      @format = format
       self
     end
 
     private
 
-    # @since v0.1.0
+    # Stores the query parameters to be set to the rescuetime host
+    attr_reader :params
+
+    # @param [String] body response body
+    # @return [Array, CSV]
     def parse_response(body)
       report = CSV.new(body,
-                         headers: true,
-                         header_converters: :symbol,
-                         converters: :all)
+                       headers: true,
+                       header_converters: :symbol,
+                       converters: :all)
 
-      case @format
+      case @format.intern
       when :array then report.to_a.map(&:to_hash)
       when :csv   then report
       else

data/lib/rescuetime/date_parser.rb

@@ -0,0 +1,86 @@
+module Rescuetime
+  # Responsible for formatting user-inputted dates into proper Rescuetime format
+  # @since v0.3.2
+  class DateParser
+    # Valid string formats for date parsing. The key is a human-readable pattern
+    # (ex. 'yyyy-mm-dd'), and the value is the corresponding regular expression.
+    DATE_FORMATS = {
+      'yyyy-mm-dd'                => /\d{4}-\d{2}-\d{2}/,
+      'yyyy/mm/dd'                => %r{\d{4}\/\d{2}\/\d{2}},
+      'mm-dd-yyyy or mm/dd/yyyy'  => %r{\d{2}[-\/]\d{2}[-\/]\d{4}/},
+      'mm-dd or mm/dd'            => %r{\d{2}[-\/]\d{2}}
+    }
+
+    class << self
+      # Returns a date as a string in the correct Rescuetime API format
+      #
+      # Allowed date formats:
+      # - Object that responds to #strftime
+      # - String in "YYYY-MM-DD" format
+      # - String in "YYYY/MM/DD" format
+      # - String in "MM-DD-YYYY" format
+      # - String in "MM/DD/YYYY" format
+      # - String in "MM-DD" format (defaults to current year)
+      # - String in "MM/DD" format (defaults to current year)
+      #
+      # @example Basic Use
+      #   parser = Rescuetime::DateParser
+      #   parser.parse '12-25' # assuming the current year is 2015
+      #   #=> '2015-12-25'
+      #
+      #   parser.parse '2015/12/25'
+      #   #=> '2015-12-25'
+      #
+      #   parser.parse Time.parse('2015-12-25')
+      #   #=> '2015-12-25'
+      #
+      #   parser.parse 'Dec. 25, 2015'
+      #   #=> Rescuetime::InvalidQueryError: Invalid date entered. Please
+      #   #                                  see docs for allowed formats.
+      #
+      # @param  [#strftime, String] date  a date to be formatted
+      # @return [String]                  a date string in the YYYY-MM-DD format
+      #
+      # @raise [Rescuetime::InvalidQueryError] if the date format is invalid
+      def parse(date)
+        if date.respond_to? :strftime
+          date.strftime '%Y-%m-%d'
+        else
+          reformat_string(date)
+        end
+      end
+
+      private
+
+      # Reformats a date string to follow the YYYY-MM-DD format
+      #
+      # @param  [String] date          A string representation of a date
+      # @param  [Hash]   formatted_as  A hash of date formats and patterns
+      # @return [String] a string date in YYYY-MM-DD format
+      #
+      # @raise [Rescuetime::InvalidQueryError] if the date format is invalid
+      def reformat_string(date, formatted_as: DATE_FORMATS)
+        case date
+        when formatted_as['yyyy-mm-dd']  then date
+        when formatted_as['yyyy/mm/dd']  then date.gsub '/', '-'
+        when formatted_as['mm-dd-yyyy or mm/dd/yyyy']
+          month, day, year = date.scan(/\d+/)
+          "#{year}-#{month}-#{day}"
+        when formatted_as['mm-dd or mm/dd']
+          year = Time.now.year
+          month, day = date.scan(/\d+/)
+          "#{year}-#{month}-#{day}"
+        else
+          fail_date_format
+        end
+      end
+
+      # Raises Rescuetime::InvalidQueryError
+      # @raise [Rescuetime::InvalidQueryError]
+      def fail_date_format(exception: Rescuetime::InvalidQueryError)
+        message = 'Invalid date entered. Please see docs for allowed formats.'
+        fail exception, message
+      end
+    end
+  end
+end

data/lib/rescuetime/errors.rb

@@ -38,7 +38,7 @@ module Rescuetime
   ##
   # Custom Errors
   # =============
-  # class CredentialsError < Error; end
+
   # Raised when a method requires credentials but none are provided
   class MissingCredentialsError < Unauthorized
     def initialize(msg = 'No API key provided. Please provide a valid key.')
@@ -68,6 +68,8 @@ module Rescuetime
   end
 
   class Error
+    # Collection of possible return status codes and corresponding Rescuetime
+    # errors
     CODES = {
       400 => Rescuetime::BadRequest,
       401 => Rescuetime::Unauthorized,

data/lib/rescuetime/query_buildable.rb

@@ -1,3 +1,5 @@
+require 'rescuetime/date_parser'
+
 module Rescuetime
   # The Rescuetime::Reportable module contains client methods relating to
   # generating requests to fetch reports on the /data endpoint of the
@@ -5,85 +7,370 @@ module Rescuetime
   #
   # @since v0.1.0
   module QueryBuildable
+    # Parameters that are included by default in every query
     BASE_PARAMS = { format:     'csv',
                     operation:  'select',
                     version:    0 }
 
-    # @return [Rescuetime::Collection]
-    # @since v0.3.0
+    # Valid values for the :order and :interval parameters
+    # @see #order_by
+    VALID = {
+      order_by: %w(time rank member),
+      interval: %w(minute hour day week month)
+    }
+
+    # Returns a Rescuetime overview report, grouping activities into their
+    # top-level categories
+    #
+    # Defaults:
+    # - order: rank
+    # - date range: current day
+    #
+    # @example Basic Use
+    #   client = Rescuetime::Client.new
+    #   client.overview
+    #   #=> #<Rescuetime::Collection:0x007f93841681a8>
+    #
+    # @return [Rescuetime::Collection] a Rescuetime Collection specifying kind
+    #                                  as an overview report
+    #
+    # @see #categories   Category report (alternative)
+    # @see #activities   Activity report (alternative)
+    # @see #productivity Productivity report (alternative)
+    # @see #efficiency   Efficiency report (alternative)
+    # @see https://www.rescuetime.com/apidoc#paramlist  Rescuetime API docs
+    #                                                   (see: restrict_kind)
     def overview
       add_to_query restrict_kind: 'overview'
     end
 
-    # @return [Rescuetime::Collection]
-    # @since v0.3.0
+    # Returns a Rescuetime category report, grouping activities into their
+    # second-level (sub-)categories
+    #
+    # Defaults:
+    # - order: rank
+    # - date range: current day
+    #
+    # @example Basic Use
+    #   client = Rescuetime::Client.new
+    #   client.categories
+    #   #=> #<Rescuetime::Collection:0x007f93841681a8>
+    #
+    # @return [Rescuetime::Collection] a Rescuetime Collection specifying kind
+    #                                  as a category report
+    #
+    # @see #overview     Overview report (alternative)
+    # @see #activities   Activity report (alternative)
+    # @see #productivity Productivity report (alternative)
+    # @see #efficiency   Efficiency report (alternative)
+    # @see https://www.rescuetime.com/apidoc#paramlist  Rescuetime API docs
+    #                                                   (see: restrict_kind)
     def categories
       add_to_query restrict_kind: 'category'
     end
 
-    # @return [Rescuetime::Collection]
-    # @since v0.1.0
+    # Returns a Rescuetime activity report, grouping activities by their
+    # specific application, website, or activity
+    #
+    # Defaults:
+    # - order: rank
+    # - date range: current day
+    #
+    # @example Basic Use
+    #   client = Rescuetime::Client.new
+    #   client.activities
+    #   #=> #<Rescuetime::Collection:0x007f93841681a8>
+    #
+    # @return [Rescuetime::Collection] a Rescuetime Collection specifying kind
+    #                                  as a activity report
+    #
+    # @see #overview     Overview report (alternative)
+    # @see #categories   Category report (alternative)
+    # @see #productivity Productivity report (alternative)
+    # @see #efficiency   Efficiency report (alternative)
+    # @see https://www.rescuetime.com/apidoc#paramlist  Rescuetime API docs
+    #                                                   (see: restrict_kind)
     def activities
       add_to_query restrict_kind: 'activity'
     end
 
-    # @return [Rescuetime::Collection]
-    # @since v0.2.0
+    # Returns a Rescuetime productivity report, featuring productivity
+    # calculations
+    #
+    # Defaults:
+    # - order: rank
+    # - date range: current day
+    #
+    # @example Basic Use
+    #   client = Rescuetime::Client.new
+    #   client.productivity
+    #   #=> #<Rescuetime::Collection:0x007f93841681a8>
+    #
+    # @return [Rescuetime::Collection] a Rescuetime Collection specifying kind
+    #                                  as a productivity report
+    #
+    # @see #overview     Overview report (alternative)
+    # @see #categories   Category report (alternative)
+    # @see #activities   Activity report (alternative)
+    # @see #efficiency   Efficiency report (alternative)
+    # @see https://www.rescuetime.com/apidoc#paramlist  Rescuetime API docs
+    #                                                   (see: restrict_kind)
     def productivity
       add_to_query restrict_kind: 'productivity'
     end
 
-    # @return [Rescuetime::Collection]
-    # @since v0.2.0
+    # Returns a Rescuetime efficiency report, featuring efficiency calculations.
+    # Defaults to chronological (time) order.
+    #
+    # Defaults:
+    # - order: time
+    # - date range: current day
+    #
+    # @example Basic Use
+    #   client = Rescuetime::Client.new
+    #   client.efficiency
+    #   #=> #<Rescuetime::Collection:0x007f93841681a8>
+    #
+    # @return [Rescuetime::Collection] a Rescuetime Collection specifying kind
+    #                                  as a efficiency report
+    #
+    # @see #overview     Overview report (alternative)
+    # @see #categories   Category report (alternative)
+    # @see #activities   Activity report (alternative)
+    # @see #productivity Productivity report (alternative)
+    # @see https://www.rescuetime.com/apidoc#paramlist  Rescuetime API docs
+    #                                                   (see: restrict_kind)
     def efficiency
-      add_to_query restrict_kind: 'efficiency', perspective: 'interval'
+      add_to_query restrict_kind: 'efficiency',
+                   perspective:   'interval'
     end
 
-    # @return [Rescuetime::Collection]
-    # @since v0.3.0
-    def order_by(order, opts = {})
-      fail(InvalidQueryError, "#{order} is not a valid order") unless
-          VALID[:order_by].include? order
-      fail(InvalidQueryError, "#{opts[:interval]} is not a valid interval") if
-          opts[:interval] && !VALID[:interval].include?(opts[:interval])
+    # Specifies the ordering and the interval of the returned Rescuetime report.
+    # For example, the results can be ordered by time, activity rank, or member;
+    # The results can be returned in intervals spanning a month, a week, a day,
+    # an hour, or 5-minutes.
+    #
+    # Efficiency reports default to :time order; everything else defaults to
+    # :rank order.
+    #
+    # @example Basic Use
+    #   client = Rescuetime::Client.new
+    #   client.order_by 'time' # interval is not required
+    #   #=> #<Rescuetime::Collection:0x007f93841681a8>
+    #
+    #   client.order_by 'rank', interval: 'hour'
+    #   #=> #<Rescuetime::Collection:0x007f93841681a8>
+    #
+    #   client.order_by :rank, interval: :hour # Symbols are also valid
+    #   #=> #<Rescuetime::Collection:0x007f93841681a8>
+    #
+    # @example Invalid Values Raise Errors
+    #   client = Rescuetime::Client.new
+    #   client.order_by 'invalid'
+    #   # => Rescuetime::InvalidQueryError: invalid is not a valid order
+    #
+    #   client.order_by 'time', interval: 'invalid'
+    #   # => Rescuetime::InvalidQueryError: invalid is not a valid interval
+    #
+    # @param  [#to_s]        order      an order for the results (ex. 'time')
+    # @param  [#intern, nil] interval   a chunking interval for results
+    #                                   (ex. 'month'). defaults to nil
+    #
+    # @return [Rescuetime::Collection]  a Rescuetime Collection specifying order
+    #                                   and interval (if set)
+    #
+    # @raise [Rescuetime::InvalidQueryError] if either order or interval are
+    #                                        invalid
+    #
+    # @see https://www.rescuetime.com/apidoc#paramlist  Rescuetime API docs
+    #                                                   (see: perspective,
+    #                                                   resolution_time)
+    # @see Rescuetime::QueryBuildable::VALID            List of valid values
+    def order_by(order, interval: nil)
+      # set order and intervals as symbols
+      order    = order.to_s
+      interval = interval ? interval.to_s : nil
 
-      add_to_query perspective: (order.to_s == 'time' ? 'interval' : order),
-                   resolution_time: opts[:interval] || opts['interval']
+      # guards against invalid order or interval
+      unless valid_order? order
+        fail InvalidQueryError, "#{order} is not a valid order"
+      end
+
+      unless valid_interval? interval
+        fail InvalidQueryError, "#{interval} is not a valid interval"
+      end
+
+      add_to_query perspective: (order == 'time' ? 'interval' : order),
+                   resolution_time: interval
     end
 
-    # @return [Rescuetime::Collection]
+    # Limits the Rescuetime report to a specific single date. To specify a date
+    # range, use #from and #to.
+    #
+    # @example Basic Use
+    #   client = Rescuetime::Client.new
+    #   client.date Date.parse('1776-07-04')
+    #   #=> #<Rescuetime::Collection:0x007f93841681a8>
+    #
+    # @example Valid Date Formats
+    #   client.date Time.parse('1776-07-04') # responds to #strftime
+    #   client.date '1776-07-04'
+    #   client.date '1776/07/04'
+    #   client.date '07-04-1776'
+    #   client.date '07/04/1776'
+    #   client.date '07-04' # defaults to current year
+    #   client.date '07/04' # defaults to current year
+    #
+    # @param  [#strftime, String]      date  a valid date-like object
+    # @return [Rescuetime::Collection]       a Rescuetime Collection specifying
+    #                                        report date
+    #
+    # @raise [Rescuetime::InvalidQueryError] if the date format is invalid
+    #
+    # @see #from
+    # @see #to
+    # @see Rescuetime::DateParser
+    # @see Rescuetime::DateParser::DATE_FORMATS         Valid date formats
+    # @see https://www.rescuetime.com/apidoc#paramlist  Rescuetime API docs
+    #                                                   (see: restrict_begin,
+    #                                                   restrict_end)
     # @since v0.3.0
     def date(date)
       add_to_query restrict_end:    to_formatted_s(date),
                    restrict_begin:  to_formatted_s(date)
     end
 
-    # @return [Rescuetime::Collection]
+    # Limits the Rescuetime report to a specific start date. If the end date is
+    # not specified, it defaults to today.
+    #
+    # @example Basic Use
+    #   client = Rescuetime::Client.new
+    #   client.from 3.days.ago
+    #   #=> #<Rescuetime::Collection:0x007f93841681a8>
+    #
+    # @example With a specified end date
+    #   client.from(2.weeks.ago).to(1.week.ago)
+    #   client.from(2.weeks.ago) # defaults to ending today
+    #
+    # @param  [#strftime, String]      date  a valid date-like object
+    # @return [Rescuetime::Collection]       a Rescuetime Collection specifying
+    #                                        report date
+    #
+    # @raise [Rescuetime::InvalidQueryError] if the date format is invalid
+    #
+    # @see #to
+    # @see #date
+    # @see Rescuetime::DateParser
+    # @see Rescuetime::DateParser::DATE_FORMATS         Valid date formats
+    # @see https://www.rescuetime.com/apidoc#paramlist  Rescuetime API docs
+    #                                                   (see: restrict_begin)
     # @since v0.3.0
     def from(date)
       add_to_query restrict_begin:  to_formatted_s(date)
     end
 
-    # @return [Rescuetime::Collection]
+    # Limits the Rescuetime report to a specific end date. Requires #from to
+    # be set before the query is sent, but it doesn't matter if that happens
+    # before or after the call to #to.
+    #
+    # @example Basic Use
+    #   client = Rescuetime::Client.new
+    #   client.from(3.days.ago).to(1.day.ago)
+    #   #=> #<Rescuetime::Collection:0x007f93841681a8>
+    #
+    # @example Requires a specified start date
+    #   client.from(2.weeks.ago).to(1.week.ago).all # valid
+    #   #=> [ ... ]
+    #
+    #   client.to(1.week.ago).from(2.weeks.ago).all # valid
+    #   #=> [ ... ]
+    #
+    #   client.to(1.week.ago).all                   # invalid!
+    #   #=> Rescuetime::InvalidQueryError
+    #
+    # @param  [#strftime, String]      date  a valid date-like object
+    # @return [Rescuetime::Collection]       a Rescuetime Collection specifying
+    #                                        report date
+    #
+    # @raise [Rescuetime::InvalidQueryError] if the date format is invalid
+    #
+    # @see #from
+    # @see #date
+    # @see Rescuetime::DateParser
+    # @see Rescuetime::DateParser::DATE_FORMATS         Valid date formats
+    # @see https://www.rescuetime.com/apidoc#paramlist  Rescuetime API docs
+    #                                                   (see: restrict_end)
     # @since v0.3.0
     def to(date)
       add_to_query restrict_end:    to_formatted_s(date)
     end
 
-    # @return [Rescuetime::Collection]
+    # Limits the Rescuetime report to specific activities and documents.
+    # The name option limits the results to those where name is an exact match;
+    # this can be used on the overview, activity, and category report. The
+    # document option limits the specific document title; this is only available
+    # on the activity report.
+    #
+    # If a value is passed for an unsupported report, it will be ignored.
+    #
+    # To see the category and document names for your account, please look at
+    # your rescuetime dashboard or generated rescuetime report.
+    #
+    # :name can be used on:
+    # - Overview report
+    # - Category report
+    # - Activity report
+    #
+    # :document can be used on:
+    # - Activity report when :name is set
+    #
+    # @example Basic Use
+    #   client = Rescuetime::Client.new
+    #   client.activities.where name: 'github.com',
+    #                           document: 'leesharma/rescuetime'
+    #   #=> #<Rescuetime::Collection:0x007f93841681a8>
+    #
+    # @example Valid reports
+    #   client.overview.where name: 'Utilities'
+    #   client.categories.where name: 'Intelligence'
+    #   client.activities.where name: 'github.com'
+    #   client.activities.where name: 'github.com', document: 'rails/rails'
+    #
+    # @example Invalid reports
+    #   client.productivity.where name: 'Intelligence'  # Invalid!
+    #   client.efficiency.where name: 'Intelligence'    # Invalid!
+    #   client.activities.where document: 'rails/rails' # Invalid!
+    #
+    # @param  [String] name      Rescuetime category name, valid on overview,
+    #                            category, and activity reports
+    # @param  [String] document  Specific document name, valid on activity
+    #                            reports when :name is set
+    #
+    # @return [Rescuetime::Collection]  a Rescuetime Collection specifying
+    #                                   category name and (optionally) document
+    # @raises [ArgumentError] if name is not set
+    #
+    # @see #overview
+    # @see #activities
+    # @see #categories
+    # @see https://www.rescuetime.com/apidoc#paramlist  Rescuetime API docs
+    #                                                   (see: restrict_thing,
+    #                                                   restrict_thingy)
     # @since v0.3.0
-    def where(options)
-      add_to_query restrict_thing:  options[:name],
-                   restrict_thingy: options[:document]
+    def where(name: nil, document: nil)
+      # Stand-in for required keyword arguments
+      name or fail ArgumentError, 'missing keyword: name'
+
+      add_to_query restrict_thing:  name,
+                   restrict_thingy: document
     end
 
     private
 
-    VALID = {
-      order_by: [:time, :rank, :member],
-      interval: [:minute, :hour, :day, :week, :month]
-    }
-
+    # Adds terms to the Rescuetime collection query
+    #
+    # @param  [Hash] terms             a set of terms to add to the query
+    # @return [Rescuetime::Collection]
     def add_to_query(**terms)
       if self.is_a? Rescuetime::Collection
         self << terms
@@ -93,22 +380,55 @@ module Rescuetime
       end
     end
 
+    # Returns a list of valid orders
+    #
+    # @return [Array<String>] a list of valid order arguments
+    # @since v0.3.2
+    def valid_orders
+      VALID[:order_by]
+    end
+
+    # Returns a list of valid intervals
+    #
+    # @return [Array<String>] a list of valid interval arguments
+    # @since v0.3.2
+    def valid_intervals
+      VALID[:interval]
+    end
+
+    # Returns true if the given order is valid
+    #
+    # @param  [#to_s]   order order to check for validity
+    # @return [Boolean]       true if the order is valid
+    # @since v0.3.2
+    def valid_order?(order)
+      valid_orders.include? order.to_s
+    end
+
+    # Returns true if the given interval is valid.
+    #
+    # @param  [#to_s]   interval interval to check for validity
+    # @return [Boolean]          true if the interval is valid
+    # @since v0.3.2
+    def valid_interval?(interval)
+      return true if interval.nil? # intervals aren't required
+      valid_intervals.include? interval.to_s
+    end
+
+    # Returns a string in the Rescuetime-date format ("YYYY-MM-DD")
+    #
+    # @param  [#strftime, String] date
+    # @param  [#parse]            date_parser  defaults to
+    #                                          Rescuetime::DateParser
+    # @return [String]            a string in 'YYYY-MM-DD' format
+    #
+    # @raise [Rescuetime::InvalidQueryError] if the date format is invalid
+    #
+    # @see Rescuetime::DateParser
+    # @see Rescuetime::DateParser::DATE_FORMATS         Valid date formats
     # @since v0.3.0
-    def to_formatted_s(date)
-      case
-      when date.respond_to?(:strftime)      then date.strftime('%Y-%m-%d')
-      when date =~ /\d{4}-\d{2}-\d{2}/      then date
-      when date =~ %r{\d{4}\/\d{2}\/\d{2}}  then date.gsub '/', '-'
-      when date =~ %r{\d{2}[-\/]\d{2}[-\/]\d{4}/}
-        date_chunks = date.scan(/\d+/)
-        "#{ date_chunks[2] }-#{ date_chunks[0] }-#{ date_chunks[1] }"
-      when date =~ %r{\d{2}[-\/]\d{2}}
-        date_chunks = date.scan(/\d+/)
-        "#{ Time.now.year }-#{ date_chunks[0] }-#{ date_chunks[1] }"
-      else
-        fail InvalidQueryError,
-             'Invalid date entered. Please see docs for allowed formats.'
-      end
+    def to_formatted_s(date, date_parser: Rescuetime::DateParser)
+      date_parser.parse(date)
     end
   end
 end

data/lib/rescuetime/requester.rb

@@ -4,37 +4,96 @@ module Rescuetime
   #
   # @since v0.2.0
   class Requester
+    # Contains bodies of error responses recieved from rescuetime.com. If one
+    # of these responses is recieved, an error will be raised.
+    INVALID = {
+      key_not_found: '"error":"# key not found","messages":"key not found"',
+      query: '"error": "# query error",'\
+      '"messages": "Error: Likely a badly formatted or missing parameter"'
+    }
+
     class << self
-      # @since v0.2.0
-      def get(host, params)
-        fail(Rescuetime::MissingCredentialsError) unless
-          params[:key] && !params[:key].to_s.empty?
+      # Performs the GET request to the specified host. Before making the
+      # request, it checks for API key presence and raises an exception if it
+      # is not present. All other exceptions require the request to go through.
+      #
+      # @param  [String] host    request host
+      # @param  [Hash]   params  request parameters
+      # @param  [#get]   http    HTTP requester
+      # @return [Faraday::Response]
+      #
+      # @raise [Rescuetime::MissingCredentialsError] if no api key is present
+      # @raise [Rescuetime::InvalidCredentialsError] if api key is incorrect
+      # @raise [Rescuetime::InvalidQueryError]       if query is badly formed
+      # @raise [Rescuetime::Error]                   if response HTTP status is
+      #                                              not 200
+      #
+      # @see Rescuetime::Client#api_key=
+      def get(host, params, http: Faraday)
+        # Fail if no api key is provided
+        unless params[:key] && !params[:key].to_s.empty?
+          fail(Rescuetime::MissingCredentialsError)
+        end
 
-        response = Faraday.get(host,
-                               params.delete_if { |_, v| !v || v.to_s.empty? })
+        req_params = params.delete_if { |_, v| !v || v.to_s.empty? }
+        response = http.get host, req_params
 
         fail_or_return response
       end
 
       private
 
-      INVALID = {
-        key_not_found: '"error":"# key not found","messages":"key not found"',
-        query: '"error": "# query error",'\
-            '"messages": "Error: Likely a badly formatted or missing parameter"'
-      }
-
+      # Checks for an error in the Rescuetime response. If an error was recieved
+      # raise the appropriate Rescuetime::Error. Otherwise, return the response.
+      #
+      # @param  [Faraday::Response] response   HTTP response from rescuetime.com
+      # @return [Faraday::Response] 200 HTTP response from rescuetime.com
+      #
+      # @raise [Rescuetime::InvalidCredentialsError] if api key is incorrect
+      # @raise [Rescuetime::InvalidQueryError]       if query is badly formed
+      # @raise [Rescuetime::Error] an error that varies based on the
+      #                             response status
       def fail_or_return(response)
-        fail Rescuetime::InvalidCredentialsError if
-          response.body =~ /#{INVALID[:key_not_found]}/
-        fail Rescuetime::InvalidQueryError if
-          response.body =~ /#{INVALID[:query]}/
+        # match the response body to known error messages with 200 status
+        case response.body
+        when key_not_found? then fail Rescuetime::InvalidCredentialsError
+        when invalid_query? then fail Rescuetime::InvalidQueryError
+        end
 
+        # check the response status for errors
         error = Rescuetime::Error::CODES[response.status.to_i]
         fail(error) if error
 
         response
       end
+
+      # Returns lambda that returns true if the response body states that the
+      # api key was not found. For use in a case statement.
+      #
+      # This check is required because rescuetime.com returns a staus of 200
+      # with this error.
+      #
+      # @return [Lambda] a lambda that returns true if the api key was not found
+      #
+      # @see Rescuetime::Requester::INVALID
+      # @since v0.3.2
+      def key_not_found?
+        ->(body) { body =~ /#{INVALID[:key_not_found]}/ }
+      end
+
+      # Returns lambda that returns true if the response body states that the
+      # query was invalid. For user in a case statement.
+      #
+      # This check is required because rescuetime.com returns a staus of 200
+      # with this error.
+      #
+      # @return [Lambda] a lambda that returns true if the query was invalid
+      #
+      # @see Rescuetime::Requester::INVALID
+      # @since v0.3.2
+      def invalid_query?
+        ->(body) { body =~ /#{INVALID[:query]}/ }
+      end
     end
   end
 end

data/lib/rescuetime/version.rb

@@ -1,5 +1,5 @@
-# Contains Rescuetime::VERSION, the gem version number
+# lib/rescuetime/version.rb
 module Rescuetime
   # rescuetime gem version number
-  VERSION = '0.3.1'
+  VERSION = '0.3.2'
 end

data/rescuetime.gemspec

@@ -31,4 +31,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec-its'
   spec.add_development_dependency 'vcr', '~> 2.9', '>= 2.9.3'
   spec.add_development_dependency 'webmock', '~> 1.21', '>= 1.21.0'
+  spec.add_development_dependency 'timecop', '~> 0.8.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rescuetime
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Lee Sharma
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-05-04 00:00:00.000000000 Z
+date: 2016-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -132,6 +132,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.21.0
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
 description: Ruby interface for the RescueTime Data Analytics API.
 email:
 - lee@leesharma.com
@@ -141,8 +155,9 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
+- ".rubocop_todo.yml"
 - ".travis.yml"
-- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - Gemfile
@@ -154,6 +169,7 @@ files:
 - lib/rescuetime.rb
 - lib/rescuetime/client.rb
 - lib/rescuetime/collection.rb
+- lib/rescuetime/date_parser.rb
 - lib/rescuetime/errors.rb
 - lib/rescuetime/query_buildable.rb
 - lib/rescuetime/requester.rb
@@ -179,7 +195,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Ruby interface for RescueTime

data/CHANGELOG.md

@@ -1,13 +0,0 @@
-# Changelog
-
-## v0.1.0 (April 15, 2015)
-
-Initial gem release
-
-### Features
-
-* Rescuetime has a version number
-* `Rescuetime::Client` exists
-* `Rescuetime::Client#api_key?` returns existence of api key
-* `Rescuetime::Client#api_key=` overwrites api key
-* `Rescuetime::Client#activities` returns list of activities