togglv8 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 04a79328e6a07a58324e23cc86e3886bbb502d18
-  data.tar.gz: 5d3ef179fe12cda05f519915fb746ef0a8080fae
+  metadata.gz: 4c535170f2f4008596f53dd97645d5946d62740e
+  data.tar.gz: f007be73994ef07272e1100e4f2046dc22d69e3a
 SHA512:
-  metadata.gz: a3cdb34425ded4ff9496cb14948ea39d539db802cf07c664a29295d6b55a403034c98a4814470fa0f3e80126eed09d828d6e3f3308f022c8fa437839bff499eb
-  data.tar.gz: cec3ad2de4a51bcc5578ce64d8ea45abeadee7b8f43b7136059d959d64bde5811f08be4693b031d39f8388513114be74e7a793e93a5a3926227fde5ccf9b4470
+  metadata.gz: 082469da76c56138a7bee169c205874a150384959b516b65633e4672288b0962fbfbccb1909ec2ad6a176bf076516d898b6a9fe3bc3bad52ac8048c2240a8d9a
+  data.tar.gz: 64463ae5e379fee5e870be1c84e4a76d0b30138634f002371cd0fd08898cf6aa9bc0530287a540ffe1a4380dcc0c51214810c9acf614aa0802d1aa43f976cbbb

data/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Change Log
+
+Notable changes are documented here following conventions outlined at [Keep a CHANGELOG](http://keepachangelog.com/).
+
+Changes that are not intended to affect usage (e.g. documentation, specs, removal of dead code, etc.) are generally not documented here.
+
+Version numbers are meant to adhere to [Semantic Versioning](http://semver.org/).
+
+
+## [Unreleased]
+
+
+## [1.2.0] - 2016-07-24
+### Added
+
+* Add support for [Toggl Reports API v2](https://github.com/toggl/toggl_api_docs/blob/master/reports.md).
+
+
+## [1.1.0] - 2016-02-22
+### Added
+
+* Add `tags(workspace_id)`.
+
+
+## [1.0.5] - 2016-02-22
+### Added
+
+* Add specs for encoding of ISO8601 times with + UTC offset. (See [1.0.4](#104---2016-01-22))
+
+
+## [1.0.4] - 2016-01-22
+### Fixed
+
+* Manually encode `+` to `%2B` before every API call. (Fixes #11)
+
+
+## [1.0.3] - 2016-01-22
+### Added
+
+* Add `debug()` method to enable debugging output including full API response.
+
+## [1.0.2] - 2015-12-12
+### Changed
+
+* Require params 'tags' and 'tag_action' in `update_time_entries_tags()`.
+
+## [1.0.1] - 2015-12-10
+### Fixed
+
+* Fix Toggl API call in `get_project_tasks()`. (Fixes #5)
+
+### Added
+
+* Add `my_tasks()`.
+* Add null checks to various methods.
+
+### Changed
+
+* Require params 'name' and 'pid' in `create_task()`.
+
+## [1.0.0] - 2015-12-06
+### Added
+
+* Add `my_deleted_projects()`.
+
+### Changed
+
+* Exclude deleted projects from `my_projects()` results.
+* Change `get_time_entries()` parameters.
+    - old: `start_timestamp=nil, end_timestamp=nil`
+    - new: `dates = {}`
+* Raise RuntimeError w/ HTTP Status code if request is not successful.
+* Handle 429 (Too Many Requests) by pausing for 1 second and retrying up to 3 times.
+    - API calls are limited to 1/sec due to toggl.com limits
+* Refactor duplication out of GET/POST/PUT/DELETE API calls.
+
+## [0.2.0] - 2015-08-21
+### Added
+
+* Add Ruby interface to most functions of [Toggl V8 API](https://github.com/toggl/toggl_api_docs/blob/master/toggl_api.md) (as of 2015-08-21).
+
+
+[Unreleased]: https://github.com/kanet77/togglv8/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/kanet77/togglv8/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/kanet77/togglv8/compare/v1.0.5...v1.1.0
+[1.0.5]: https://github.com/kanet77/togglv8/compare/v1.0.4...v1.0.5
+[1.0.4]: https://github.com/kanet77/togglv8/compare/v1.0.3...v1.0.4
+[1.0.3]: https://github.com/kanet77/togglv8/compare/v1.0.2...v1.0.3
+[1.0.2]: https://github.com/kanet77/togglv8/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/kanet77/togglv8/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/kanet77/togglv8/compare/v0.2.0...v1.0.0
+[0.2.0]: https://github.com/kanet77/togglv8/compare/a1d5cc5...v0.2.0

data/README.md

@@ -7,7 +7,11 @@
 
 [togglv8](/) is a Ruby Wrapper for [Toggl API v8](https://github.com/toggl/toggl_api_docs). It is designed to mirror the Toggl API as closely as possible.
 
-**Note:** Currently togglv8 only includes calls to [Toggl API](https://github.com/toggl/toggl_api_docs/blob/master/toggl_api.md), not the [Reports API](https://github.com/toggl/toggl_api_docs/blob/master/reports.md)
+togglv8 supports both [Toggl API](https://github.com/toggl/toggl_api_docs/blob/master/toggl_api.md) and [Reports API](https://github.com/toggl/toggl_api_docs/blob/master/reports.md)
+
+## Change Log
+
+See [CHANGELOG](CHANGELOG.md) for a summary of notable changes in each version.
 
 ## Installation
 
@@ -25,24 +29,77 @@ Or install it yourself as:
 
     $ gem install togglv8
 
+## Initialization
+
+### TogglV8::API
+
+TogglV8::API communicates with [Toggl API v8](https://github.com/toggl/toggl_api_docs/blob/master/toggl_api.md) and can be initialized in one of three ways.
+
+```ruby
+TogglV8::API.new                      # reads API token from file ~/.toggl
+TogglV8::API.new(api_token)           # explicit API token
+TogglV8::API.new(username, password)  # username & password
+```
+
+### TogglV8::ReportsV2
+
+TogglV8::ReportsV2 communicates with [Toggl Reports API v2](https://github.com/toggl/toggl_api_docs/blob/master/reports.md) and can be initialized in one of three ways. Toggl.com requires authentication with an API token for Reports API v2.
+
+```ruby
+TogglV8::ReportsV2.new                              # reads API token from file ~/.toggl
+TogglV8::ReportsV2.new(toggl_api_file: toggl_file)  # reads API token from toggl_file
+TogglV8::ReportsV2.new(api_token: api_token)        # explicit API token
+```
+
+**Note:** `workspace_id` must be set in order to generate reports.
+
+```ruby
+toggl = TogglV8::API.new
+reports = TogglV8::ReportsV2.new
+reports.workspace_id = toggl.workspaces.first['id']
+```
+
 ## Usage
 
-This short example shows one way to create a time entry for the first workspace of the user identified by `<API_TOKEN>`:
+This short example shows one way to create a time entry for the first workspace of the user identified by `<API_TOKEN>`. It then generates various reports containing that time entry.
 
 ```ruby
 require 'togglv8'
+require 'json'
 
 toggl_api    = TogglV8::API.new(<API_TOKEN>)
 user         = toggl_api.me(all=true)
 workspaces   = toggl_api.my_workspaces(user)
 workspace_id = workspaces.first['id']
-toggl_api.create_time_entry({
-  'description' => "Workspace time entry",
+time_entry   = toggl_api.create_time_entry({
+  'description' => "My awesome workspace time entry",
   'wid' => workspace_id,
   'duration' => 1200,
-  'start' => "2015-08-18T01:13:40.000Z",
+  'start' => toggl_api.iso8601((Time.now - 3600).to_datetime),
   'created_with' => "My awesome Ruby application"
 })
+
+begin
+  reports               = TogglV8::ReportsV2.new(api_token: <API_TOKEN>)
+  begin
+    reports.summary
+  rescue Exception => e
+    puts e.message      # workspace_id is required
+  end
+  reports.workspace_id  = workspace_id
+  summary               = reports.summary
+  puts "Generating summary JSON..."
+  puts JSON.pretty_generate(summary)
+  puts "Generating summary PDF..."
+  reports.write_summary('toggl_summary.pdf')
+  puts "Generating weekly CSV..."
+  reports.write_weekly('toggl_weekly.csv')
+  puts "Generating details XLS..."
+  reports.write_details('toggl_details.xls')
+  # Note: toggl.com does not generate Weekly XLS report (as of 2016-07-24)
+ensure
+  toggl_api.delete_time_entry(time_entry['id'])
+end
 ```
 
 See specs for more examples.
@@ -53,7 +110,7 @@ See specs for more examples.
 
 ## Debugging
 
-The `TogglV8::API#debug` method determines if debug output is printed to STDOUT. (The default is `true`.) This code snippet demonstrates the debug output.
+The `TogglV8::API#debug` method determines if debug output is printed to STDOUT. This code snippet demonstrates the debug output.
 
 ```ruby
 require 'togglv8'
@@ -79,6 +136,12 @@ Also available on [DocumentUp](https://documentup.com/kanet77/togglv8)
 
 ## Acknowledgements
 
+- Thanks to the following contributors (in alphabetical order):
+    * [archonic](https://github.com/archonic) ([fork](https://github.com/archonic/togglv8))
+    * [ddiatmb](https://github.com/ddiatmb) ([fork](https://github.com/ddiatmb/togglv8))
+    * [itaymendel](https://github.com/itaymendel)
+    * [ppawlikmb](https://github.com/ppawlikmb) ([fork](https://github.com/ppawlikmb/togglv8))
+    * [worldsmithroy](https://github.com/worldsmithroy) ([fork](https://github.com/worldsmithroy/togglv8))
 - Thanks to [Koen Van der Auwera](https://github.com/atog) for the [Ruby Wrapper for Toggl API v6](https://github.com/atog/toggl)
 - Thanks to the Toggl team for exposing the API.
 

data/lib/logging.rb

@@ -0,0 +1,36 @@
+require 'logger'
+require 'awesome_print' # for debug output
+
+# From http://stackoverflow.com/questions/917566/ruby-share-logger-instance-among-module-classes
+module Logging
+  class << self
+    def logger
+      @logger ||= Logger.new($stdout)
+    end
+
+    def logger=(logger)
+      @logger = logger
+    end
+  end
+
+  # Addition
+  def self.included(base)
+    class << base
+      def logger
+        Logging.logger
+      end
+    end
+  end
+
+  def logger
+    Logging.logger
+  end
+
+  def debug(debug=true)
+    if debug
+      logger.level = Logger::DEBUG
+    else
+      logger.level = Logger::WARN
+    end
+  end
+end

data/lib/reportsv2.rb

@@ -0,0 +1,148 @@
+module TogglV8
+  TOGGL_REPORTS_URL = 'https://toggl.com/reports/api/'
+
+  class ReportsV2
+    include TogglV8::Connection
+
+    REPORTS_V2_URL = TOGGL_REPORTS_URL + 'v2/'
+
+    attr_reader :conn
+
+    attr_accessor :workspace_id
+
+    def initialize(opts={})
+      debug(false)
+
+      @user_agent = 'togglv8'
+
+      username = opts[:api_token]
+      if username.nil?
+        toggl_api_file = opts[:toggl_api_file] || File.join(Dir.home, TOGGL_FILE)
+        if FileTest.exist?(toggl_api_file) then
+          username = IO.read(toggl_api_file)
+        else
+          raise "Expecting\n" +
+            " 1) api_token in file #{toggl_api_file}, or\n" +
+            " 2) parameter: (api_token), or\n" +
+            "\n\tSee https://github.com/toggl/toggl_api_docs/blob/master/reports.md#authentication"
+        end
+      end
+
+      @conn = TogglV8::Connection.open(username, API_TOKEN, REPORTS_V2_URL, opts)
+    end
+
+    ##
+    # ---------
+    # :section: Reports
+    #
+    # The following parameters and filters can be used in all of the reports
+    #
+    # user_agent              : the name of this application so Toggl can get in touch
+    #                           (string, *required*)
+    # workspace_id            : The workspace whose data you want to access.
+    #                           (integer, *required*)
+    # since                   : ISO 8601 date (YYYY-MM-DD), by default until - 6 days.
+    #                           (string)
+    # until                   : ISO 8601 date (YYYY-MM-DD), by default today
+    #                           (string)
+    # billable                : possible values: yes/no/both, default both
+    # client_ids              : client ids separated by a comma, 0 if you want to filter out time entries without a client
+    # project_ids             : project ids separated by a comma, 0 if you want to filter out time entries without a project
+    # user_ids                : user ids separated by a comma
+    # members_of_group_ids    : group ids separated by a comma. This limits provided user_ids to the provided group members
+    # or_members_of_group_ids : group ids separated by a comma. This extends provided user_ids with the provided group members
+    # tag_ids                 : tag ids separated by a comma, 0 if you want to filter out time entries without a tag
+    # task_ids                : task ids separated by a comma, 0 if you want to filter out time entries without a task
+    # time_entry_ids          : time entry ids separated by a comma
+    # description             : time entry description
+    #                           (string)
+    # without_description     : filters out the time entries which do not have a description ('(no description)')
+    #                           (true/false)
+    # order_field             : date/description/duration/user in detailed reports
+    #                           title/duration/amount in summary reports
+    #                           title/day1/day2/day3/day4/day5/day6/day7/week_total in weekly report
+    # order_desc              : on for descending and off for ascending order
+    #                           (on/off)
+    # distinct_rates          : on/off, default off
+    # rounding                : on/off, default off, rounds time according to workspace settings
+    # display_hours           : decimal/minutes, display hours with minutes or as a decimal number, default minutes
+    #
+    # NB! Maximum date span (until - since) is one year.
+
+    # extension can be one of ['.pdf', '.csv', '.xls']. Possibly others?
+    def report(type, extension, opts)
+      raise "workspace_id is required" if @workspace_id.nil?
+      get "#{type}#{extension}", {
+        'user_agent': @user_agent,
+        'workspace_id': @workspace_id,
+      }.merge(opts)
+    end
+
+    def weekly(extension='', opts={})
+      report('weekly', extension, opts)
+    end
+
+    def details(extension='', opts={})
+      report('details', extension, opts)
+    end
+
+    def summary(extension='', opts={})
+      report('summary', extension, opts)
+    end
+
+    def write_report(filename)
+      extension = File.extname(filename)
+      report = yield(extension)
+      File.open(filename, "wb") do |file|
+        file.write(report)
+      end
+    end
+
+    def write_weekly(filename, opts={})
+      write_report(filename) do |extension|
+        weekly(extension, opts)
+      end
+    end
+
+    def write_details(filename, opts={})
+      write_report(filename) do |extension|
+        details(extension, opts)
+      end
+    end
+
+    def write_summary(filename, opts={})
+      write_report(filename) do |extension|
+        summary(extension, opts)
+      end
+    end
+
+    def revision
+      get "revision"
+    end
+
+    def index
+      get "index"
+    end
+
+    def project(opts={})
+      raise "workspace_id is required" if @workspace_id.nil?
+      get "project", {
+        'user_agent': @user_agent,
+        'workspace_id': @workspace_id,
+      }.merge(opts)
+    end
+
+    def env
+      get "env"
+    end
+
+    def error400
+      get "error400"
+    end
+
+    def error500
+      get "error500"
+    end
+
+  end
+end

data/lib/togglv8.rb

@@ -1,144 +1,9 @@
-require 'faraday'
-require 'oj'
+require_relative 'togglv8/version'
 
-require 'logger'
-require 'awesome_print' # for debug output
+require_relative 'togglv8/connection'
 
-require_relative 'togglv8/clients'
-require_relative 'togglv8/dashboard'
-require_relative 'togglv8/project_users'
-require_relative 'togglv8/projects'
-require_relative 'togglv8/tags'
-require_relative 'togglv8/tasks'
-require_relative 'togglv8/time_entries'
-require_relative 'togglv8/users'
-require_relative 'togglv8/version'
-require_relative 'togglv8/workspaces'
+require_relative 'togglv8/togglv8'
+require_relative 'reportsv2'
 
 # :mode => :compat will convert symbols to strings
 Oj.default_options = { :mode => :compat }
-
-module TogglV8
-  TOGGL_API_URL = 'https://www.toggl.com/api/'
-  DELAY_SEC = 1
-  MAX_RETRIES = 3
-
-  class API
-    TOGGL_API_V8_URL = TOGGL_API_URL + 'v8/'
-    API_TOKEN = 'api_token'
-    TOGGL_FILE = '.toggl'
-
-    attr_reader :conn
-
-    def initialize(username=nil, password=API_TOKEN, opts={})
-      @logger = Logger.new(STDOUT)
-      @logger.level = Logger::WARN
-
-      if username.nil? && password == API_TOKEN
-        toggl_api_file = File.join(Dir.home, TOGGL_FILE)
-        if FileTest.exist?(toggl_api_file) then
-          username = IO.read(toggl_api_file)
-        else
-          raise "Expecting\n" +
-            " 1) api_token in file #{toggl_api_file}, or\n" +
-            " 2) parameter: (api_token), or\n" +
-            " 3) parameters: (username, password).\n" +
-            "\n\tSee https://github.com/toggl/toggl_api_docs/blob/master/chapters/authentication.md"
-        end
-      end
-
-      @conn = TogglV8::API.connection(username, password, opts)
-    end
-
-    def debug(debug=true)
-      if debug
-        @logger.level = Logger::DEBUG
-      else
-        @logger.level = Logger::WARN
-      end
-    end
-
-  #---------#
-  # Private #
-  #---------#
-
-  private
-
-    attr_writer :conn
-
-    def self.connection(username, password, opts={})
-      Faraday.new(:url => TOGGL_API_V8_URL, :ssl => {:verify => true}) do |faraday|
-        faraday.request :url_encoded
-        faraday.response :logger, Logger.new('faraday.log') if opts[:log]
-        faraday.adapter Faraday.default_adapter
-        faraday.headers = { "Content-Type" => "application/json" }
-        faraday.basic_auth username, password
-      end
-    end
-
-    def requireParams(params, fields=[])
-      raise ArgumentError, 'params is not a Hash' unless params.is_a? Hash
-      return if fields.empty?
-      errors = []
-      for f in fields
-        errors.push("params[#{f}] is required") unless params.has_key?(f)
-      end
-      raise ArgumentError, errors.join(', ') if !errors.empty?
-    end
-
-    def _call_api(procs)
-      @logger.debug(procs[:debug_output].call)
-      full_resp = nil
-      i = 0
-      loop do
-        i += 1
-        full_resp = procs[:api_call].call
-        @logger.ap(full_resp.env, :debug)
-        break if full_resp.status != 429 || i >= MAX_RETRIES
-        sleep(DELAY_SEC)
-      end
-
-      raise "HTTP Status: #{full_resp.status}" unless full_resp.success?
-      return {} if full_resp.body.nil? || full_resp.body == 'null'
-
-      full_resp
-    end
-
-    def get(resource)
-      resource.gsub!('+', '%2B')
-      full_resp = _call_api(debug_output: lambda { "GET #{resource}" },
-                            api_call: lambda { self.conn.get(resource) } )
-      return {} if full_resp == {}
-      resp = Oj.load(full_resp.body)
-      return resp['data'] if resp.respond_to?(:has_key?) && resp.has_key?('data')
-      resp
-    end
-
-    def post(resource, data='')
-      resource.gsub!('+', '%2B')
-      full_resp = _call_api(debug_output: lambda { "POST #{resource} / #{data}" },
-                            api_call: lambda { self.conn.post(resource, Oj.dump(data)) } )
-      return {} if full_resp == {}
-      resp = Oj.load(full_resp.body)
-      resp['data']
-    end
-
-    def put(resource, data='')
-      resource.gsub!('+', '%2B')
-      full_resp = _call_api(debug_output: lambda { "PUT #{resource} / #{data}" },
-                            api_call: lambda { self.conn.put(resource, Oj.dump(data)) } )
-      return {} if full_resp == {}
-      resp = Oj.load(full_resp.body)
-      resp['data']
-    end
-
-    def delete(resource)
-      resource.gsub!('+', '%2B')
-      full_resp = _call_api(debug_output: lambda { "DELETE #{resource}" },
-                            api_call: lambda { self.conn.delete(resource) } )
-      return {} if full_resp == {}
-      full_resp.body
-    end
-
-  end
-end

data/lib/togglv8/connection.rb

@@ -0,0 +1,118 @@
+require 'faraday'
+require 'oj'
+
+require_relative '../logging'
+
+module TogglV8
+  module Connection
+    include Logging
+
+    DELAY_SEC = 1
+    MAX_RETRIES = 3
+
+    API_TOKEN = 'api_token'
+    TOGGL_FILE = '.toggl'
+
+    def self.qualify(username, password)
+      if username.nil? && password == API_TOKEN
+        toggl_api_file = File.join(Dir.home, TOGGL_FILE)
+
+        # logger.debug("toggl_api_file = #{toggl_api_file}")
+        if FileTest.exist?(toggl_api_file) then
+          username = IO.read(toggl_api_file)
+        else
+          raise "Expecting\n" +
+            " 1) api_token in file #{toggl_api_file}, or\n" +
+            " 2) parameter: (api_token), or\n" +
+            " 3) parameters: (username, password).\n" +
+            "\n\tSee https://github.com/toggl/toggl_api_docs/blob/master/chapters/authentication.md"
+        end
+      end
+      return username, password
+    end
+
+    def self.open(username=nil, password=API_TOKEN, url=nil, opts={})
+      username, password = qualify(username, password)
+      raise 'Missing URL' if url.nil?
+
+      Faraday.new(:url => url, :ssl => {:verify => true}) do |faraday|
+        faraday.request :url_encoded
+        faraday.response :logger, Logger.new('faraday.log') if opts[:log]
+        faraday.adapter Faraday.default_adapter
+        faraday.headers = { "Content-Type" => "application/json" }
+        faraday.basic_auth username, password
+      end
+    end
+
+    def requireParams(params, fields=[])
+      raise ArgumentError, 'params is not a Hash' unless params.is_a? Hash
+      return if fields.empty?
+      errors = []
+      for f in fields
+      errors.push("params[#{f}] is required") unless params.has_key?(f)
+      end
+      raise ArgumentError, errors.join(', ') if !errors.empty?
+    end
+
+    def _call_api(procs)
+      # logger.debug(procs[:debug_output].call)
+      full_resp = nil
+      i = 0
+      loop do
+        i += 1
+        full_resp = procs[:api_call].call
+        logger.ap(full_resp.env, :debug)
+        break if full_resp.status != 429 || i >= MAX_RETRIES
+        sleep(DELAY_SEC)
+      end
+
+      raise full_resp.headers['warning'] if full_resp.headers['warning']
+      raise "HTTP Status: #{full_resp.status}" unless full_resp.success?
+      return {} if full_resp.body.nil? || full_resp.body == 'null'
+
+      full_resp
+    end
+
+    def get(resource, params={})
+      query_params = params.map { |k,v| "#{k}=#{v}" }.join('&')
+      resource += "?#{query_params}" unless query_params.empty?
+      resource.gsub!('+', '%2B')
+      full_resp = _call_api(debug_output: lambda { "GET #{resource}" },
+                  api_call: lambda { self.conn.get(resource) } )
+      return {} if full_resp == {}
+      begin
+        resp = Oj.load(full_resp.body)
+        return resp['data'] if resp.respond_to?(:has_key?) && resp.has_key?('data')
+        return resp
+      rescue Oj::ParseError
+        return full_resp.body
+      end
+    end
+
+    def post(resource, data='')
+      resource.gsub!('+', '%2B')
+      full_resp = _call_api(debug_output: lambda { "POST #{resource} / #{data}" },
+                  api_call: lambda { self.conn.post(resource, Oj.dump(data)) } )
+      return {} if full_resp == {}
+      resp = Oj.load(full_resp.body)
+      resp['data']
+    end
+
+    def put(resource, data='')
+      resource.gsub!('+', '%2B')
+      full_resp = _call_api(debug_output: lambda { "PUT #{resource} / #{data}" },
+                  api_call: lambda { self.conn.put(resource, Oj.dump(data)) } )
+      return {} if full_resp == {}
+      resp = Oj.load(full_resp.body)
+      resp['data']
+    end
+
+    def delete(resource)
+      resource.gsub!('+', '%2B')
+      full_resp = _call_api(debug_output: lambda { "DELETE #{resource}" },
+                  api_call: lambda { self.conn.delete(resource) } )
+      return {} if full_resp == {}
+      full_resp.body
+    end
+  end
+end

data/lib/togglv8/togglv8.rb

@@ -0,0 +1,40 @@
+require_relative 'clients'
+require_relative 'dashboard'
+require_relative 'project_users'
+require_relative 'projects'
+require_relative 'tags'
+require_relative 'tasks'
+require_relative 'time_entries'
+require_relative 'users'
+require_relative 'version'
+require_relative 'workspaces'
+
+module TogglV8
+  TOGGL_API_URL = 'https://www.toggl.com/api/'
+
+  class API
+    include TogglV8::Connection
+
+    TOGGL_API_V8_URL = TOGGL_API_URL + 'v8/'
+
+    attr_reader :conn
+
+    def initialize(username=nil, password=API_TOKEN, opts={})
+      debug(false)
+      @conn = TogglV8::Connection.open(username, password,
+                TOGGL_API_V8_URL, opts)
+    end
+  end
+end
+
+
+
+
+
+
+
+
+
+
+
+

data/lib/togglv8/version.rb

@@ -1,4 +1,4 @@
 module TogglV8
   # :section:
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/spec/lib/reportsv2_spec.rb

@@ -0,0 +1,198 @@
+require 'fileutils'
+
+describe 'ReportsV2' do
+  it 'initializes with api_token' do
+    reports = TogglV8::ReportsV2.new(api_token: Testing::API_TOKEN)
+    env = reports.env
+    expect(env).to_not be nil
+    expect(env['user']['api_token']).to eq Testing::API_TOKEN
+  end
+
+  it 'does not initialize with bogus api_token' do
+    reports = TogglV8::ReportsV2.new(api_token: '4880nqor1orr9n241sn08070q33oq49s')
+    expect { reports.env }.to raise_error(RuntimeError, "HTTP Status: 401")
+  end
+
+  context '.toggl file' do
+    before :each do
+      @home = File.join(Dir.pwd, "tmp")
+      Dir.mkdir(@home)
+
+      @original_home = Dir.home
+      ENV['HOME'] = @home
+    end
+
+    after :each do
+      FileUtils.rm_rf(@home)
+      ENV['HOME'] = @original_home
+    end
+
+    it 'initializes with .toggl file' do
+      toggl_file = File.join(@home, '.toggl')
+      File.open(toggl_file, 'w') { |file| file.write(Testing::API_TOKEN) }
+
+      reports = TogglV8::ReportsV2.new
+      env = reports.env
+      expect(env).to_not be nil
+      expect(env['user']['api_token']).to eq Testing::API_TOKEN
+    end
+
+    it 'initializes with custom toggl file' do
+      toggl_file = File.join(@home, 'my_toggl')
+      File.open(toggl_file, 'w') { |file| file.write(Testing::API_TOKEN) }
+
+      reports = TogglV8::ReportsV2.new({toggl_api_file: toggl_file})
+      env = reports.env
+      expect(env).to_not be nil
+      expect(env['user']['api_token']).to eq Testing::API_TOKEN
+    end
+
+    it 'raises error if .toggl file is missing' do
+      expect{ reports = TogglV8::ReportsV2.new }.to raise_error(RuntimeError)
+    end
+  end
+
+  context 'handles errors' do
+    before :all do
+      @reports = TogglV8::ReportsV2.new(api_token: Testing::API_TOKEN)
+      @reports.workspace_id = @workspace_id
+    end
+
+    it 'surfaces a Warning HTTP header in case of error' do
+      # https://github.com/toggl/toggl_api_docs/blob/master/reports.md#failed-requests
+      expect { @reports.error400 }.to raise_error(RuntimeError,
+                                      "This URL is intended only for testing")
+    end
+
+    it 'retries a request up to 3 times if a 429 is received' do
+      expect(@reports.conn).to receive(:get).exactly(3).times.and_return(
+        MockResponse.new(429, {}, 'body'))
+      expect { @reports.env }.to raise_error(RuntimeError, "HTTP Status: 429")
+    end
+
+    it 'retries a request after 429' do
+      expect(@reports.conn).to receive(:get).twice.and_return(
+        MockResponse.new(429, {}, 'body'),
+        MockResponse.new(200, {}, 'rev1.2.3'))
+      expect(@reports.revision).to eq('rev1.2.3')
+    end
+  end
+
+  context 'revision' do
+    it 'has not changed' do
+      reports = TogglV8::ReportsV2.new(api_token: Testing::API_TOKEN)
+      reports.workspace_id = @workspace_id
+      expect(reports.revision).to eq("0.0.38\n-8a007ca")
+    end
+  end
+
+  context 'blank reports' do
+    before :all do
+      @toggl = TogglV8::API.new(Testing::API_TOKEN)
+      @workspaces = @toggl.workspaces
+      @workspace_id = @workspaces.first['id']
+      @reports = TogglV8::ReportsV2.new(api_token: Testing::API_TOKEN)
+      @reports.workspace_id = @workspace_id
+    end
+
+    it 'summary' do
+      expect(@reports.summary).to eq []
+    end
+
+    it 'weekly' do
+      expect(@reports.weekly).to eq []
+    end
+
+    it 'details' do
+      expect(@reports.details).to eq []
+    end
+  end
+
+  context 'reports' do
+    before :all do
+      @toggl = TogglV8::API.new(Testing::API_TOKEN)
+      @workspaces = @toggl.workspaces
+      @workspace_id = @workspaces.first['id']
+      time_entry_info = {
+        'wid' => @workspace_id,
+        'start' => @toggl.iso8601(DateTime.now),
+        'duration' => 77
+      }
+
+      @time_entry = @toggl.create_time_entry(time_entry_info)
+
+      @reports = TogglV8::ReportsV2.new(api_token: Testing::API_TOKEN)
+      @reports.workspace_id = @workspace_id
+    end
+
+    after :all do
+      @toggl.delete_time_entry(@time_entry['id'])
+    end
+
+    it 'summary' do
+      summary = @reports.summary
+      expect(summary.length).to eq 1
+      expect(summary.first['time']).to eq 77000
+      expect(summary.first['items'].length).to eq 1
+      expect(summary.first['items'].first['time']).to eq 77000
+    end
+
+    it 'weekly' do
+      weekly = @reports.weekly
+      expect(weekly.length).to eq 1
+      expect(weekly.first['details'].first['title']['user']).to eq 'togglv8'
+      expect(weekly.first['totals'][7]).to eq 77000
+    end
+
+    it 'details' do
+      details = @reports.details
+      expect(details.length).to eq 1
+      expect(details.first['user']).to eq 'togglv8'
+      expect(details.first['dur']).to eq 77000
+    end
+  end
+
+  context 'CSV reports' do
+    before :all do
+      @toggl = TogglV8::API.new(Testing::API_TOKEN)
+      @workspaces = @toggl.workspaces
+      @workspace_id = @workspaces.first['id']
+      time_entry_info = {
+        'wid' => @workspace_id,
+        'start' => @toggl.iso8601(DateTime.now),
+        'duration' => 77
+      }
+
+      @time_entry = @toggl.create_time_entry(time_entry_info)
+
+      @reports = TogglV8::ReportsV2.new(api_token: Testing::API_TOKEN)
+      @reports.workspace_id = @workspace_id
+    end
+
+    after :all do
+      @toggl.delete_time_entry(@time_entry['id'])
+    end
+
+    it 'summary' do
+      summary = @reports.summary
+      expect(summary.length).to eq 1
+      expect(summary.first['time']).to eq 77000
+      expect(summary.first['items'].length).to eq 1
+      expect(summary.first['items'].first['time']).to eq 77000
+    end
+
+    it 'weekly' do
+      weekly = @reports.weekly
+      expect(weekly.length).to eq 1
+      expect(weekly.first['details'].first['title']['user']).to eq 'togglv8'
+      expect(weekly.first['totals'][7]).to eq 77000
+    end
+
+    it 'details' do
+      details = @reports.details
+      expect(details.length).to eq 1
+      expect(details.first['user']).to eq 'togglv8'
+      expect(details.first['dur']).to eq 77000
+    end
+  end
+end

data/spec/lib/togglv8_spec.rb

@@ -1,6 +1,6 @@
 require 'fileutils'
 
-describe 'TogglV8::API' do
+describe 'TogglV8' do
   it 'initializes with api_token' do
     toggl = TogglV8::API.new(Testing::API_TOKEN)
     me = toggl.me
@@ -55,25 +55,24 @@ describe 'TogglV8::API' do
   context 'handles errors' do
     before :all do
       @toggl = TogglV8::API.new(Testing::API_TOKEN)
-      Response = Struct.new(:env, :status, :success?, :body)
     end
 
     it 'surfaces an HTTP Status Code in case of error' do
       expect(@toggl.conn).to receive(:get).once.and_return(
-        Response.new('', 400, false, nil))
+        MockResponse.new(400, {}, 'body'))
       expect { @toggl.me }.to raise_error(RuntimeError, "HTTP Status: 400")
     end
 
     it 'retries a request up to 3 times if a 429 is received' do
       expect(@toggl.conn).to receive(:get).exactly(3).times.and_return(
-        Response.new('', 429, false, nil))
+        MockResponse.new(429, {}, 'body'))
       expect { @toggl.me }.to raise_error(RuntimeError, "HTTP Status: 429")
     end
 
     it 'retries a request after 429' do
       expect(@toggl.conn).to receive(:get).twice.and_return(
-        Response.new('', 429, false, nil),
-        Response.new('', 200, true, nil))
+        MockResponse.new(429, {}, 'body'),
+        MockResponse.new(200, {}, nil))
       expect(@toggl.me).to eq({})   # response is {} in this case because body is nil
     end
   end

data/spec/spec_helper.rb

@@ -1,7 +1,7 @@
 require "simplecov"
 require "coveralls"
 
-SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
+SimpleCov.formatters = [
   SimpleCov::Formatter::HTMLFormatter,
   Coveralls::SimpleCov::Formatter
 ]
@@ -32,7 +32,23 @@ RSpec.configure do |config|
 
   config.before(:suite) do
     toggl = TogglV8::API.new(Testing::API_TOKEN)
-    TogglV8SpecHelper.setUp(toggl)
+    TogglV8SpecHelper.setUp(toggl)  # start tests from known state
+  end
+end
+
+class MockResponse
+  # https://github.com/lostisland/faraday/blob/master/lib/faraday/response.rb
+
+  attr_accessor :status, :headers, :body, :env
+
+  def initialize(status, headers, body)
+    @status = status
+    @headers = headers
+    @body = body
+  end
+
+  def success?
+    @status == 200
   end
 end
 

data/spec/togglv8_spec_helper.rb

@@ -1,9 +1,7 @@
 require_relative '../lib/togglv8'
-require 'logger'
 
 class TogglV8SpecHelper
-  @logger = Logger.new(STDOUT)
-  @logger.level = Logger::WARN
+  include Logging
 
   def self.setUp(toggl)
     user = toggl.me(all=true)
@@ -20,7 +18,7 @@ class TogglV8SpecHelper
     clients = toggl.my_clients
     unless clients.nil?
       client_ids ||= clients.map { |c| c['id'] }
-      @logger.debug("Deleting #{client_ids.length} clients")
+      # logger.debug("Deleting #{client_ids.length} clients")
       client_ids.each do |c_id|
         toggl.delete_client(c_id)
       end
@@ -31,7 +29,7 @@ class TogglV8SpecHelper
     projects = toggl.projects(@default_workspace_id)
     unless projects.nil?
       project_ids ||= projects.map { |p| p['id'] }
-      @logger.debug("Deleting #{project_ids.length} projects")
+      # logger.debug("Deleting #{project_ids.length} projects")
       return unless project_ids.length > 0
       toggl.delete_projects(project_ids)
     end
@@ -41,7 +39,7 @@ class TogglV8SpecHelper
     tags = toggl.my_tags
     unless tags.nil?
       tag_ids ||= tags.map { |t| t['id'] }
-      @logger.debug("Deleting #{tag_ids.length} tags")
+      # logger.debug("Deleting #{tag_ids.length} tags")
       tag_ids.each do |t_id|
         toggl.delete_tag(t_id)
       end
@@ -53,7 +51,7 @@ class TogglV8SpecHelper
       { :start_date => DateTime.now - 30, :end_date => DateTime.now + 30 } )
     unless time_entries.nil?
       time_entry_ids ||= time_entries.map { |t| t['id'] }
-      @logger.debug("Deleting #{time_entry_ids.length} time_entries")
+      # logger.debug("Deleting #{time_entry_ids.length} time_entries")
       time_entry_ids.each do |t_id|
         toggl.delete_time_entry(t_id)
       end
@@ -66,7 +64,7 @@ class TogglV8SpecHelper
     unless workspaces.nil?
       workspace_ids ||= workspaces.map { |w| w['id'] }
       workspace_ids.delete(user['default_wid'])
-      @logger.debug("Leaving #{workspace_ids.length} workspaces")
+      # logger.debug("Leaving #{workspace_ids.length} workspaces")
       workspace_ids.each do |w_id|
         toggl.leave_workspace(w_id)
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: togglv8
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Tom Kane
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-23 00:00:00.000000000 Z
+date: 2016-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -176,21 +176,27 @@ files:
 - ".rdoc_options"
 - ".rspec"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- lib/logging.rb
+- lib/reportsv2.rb
 - lib/togglv8.rb
 - lib/togglv8/clients.rb
+- lib/togglv8/connection.rb
 - lib/togglv8/dashboard.rb
 - lib/togglv8/project_users.rb
 - lib/togglv8/projects.rb
 - lib/togglv8/tags.rb
 - lib/togglv8/tasks.rb
 - lib/togglv8/time_entries.rb
+- lib/togglv8/togglv8.rb
 - lib/togglv8/users.rb
 - lib/togglv8/version.rb
 - lib/togglv8/workspaces.rb
+- spec/lib/reportsv2_spec.rb
 - spec/lib/togglv8/clients_spec.rb
 - spec/lib/togglv8/dashboard_spec.rb
 - spec/lib/togglv8/projects_spec.rb
@@ -228,6 +234,7 @@ signing_key:
 specification_version: 4
 summary: Toggl v8 API wrapper (See https://github.com/toggl/toggl_api_docs)
 test_files:
+- spec/lib/reportsv2_spec.rb
 - spec/lib/togglv8/clients_spec.rb
 - spec/lib/togglv8/dashboard_spec.rb
 - spec/lib/togglv8/projects_spec.rb