togglv8-ng 1.4.0

data/.travis.yml

@@ -0,0 +1,16 @@
+language: ruby
+rvm:
+  - ruby-head
+  - 2.4.0
+  - 2.3.3
+  - 2.2.6
+  - 2.1.10
+  - 2.0.0-p648
+script: bundle exec rspec --format documentation
+cache: bundler
+branches:
+  only:
+    - master
+addons:
+  code_climate:
+    repo_token: eb44970f9efc497fb68c6ec1ce051dea530776b6a5bbe75e57734625f761ac86

data/CHANGELOG.md

@@ -0,0 +1,101 @@
+# 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.1] - 2016-07-25
+### Changed
+
+* Fix ReportsV2#project by requiring project_id.
+* Improve spec code coverage.
+* Include version in `user_agent` and `created_with` (e.g. TogglV8 v1.2.1)
+
+
+## [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.1...HEAD
+[1.2.1]: https://github.com/kanet77/togglv8/compare/v1.2.0...v1.2.1
+[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/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in togglv8.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013-2015 Tom Kane
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,160 @@
+
+# Toggl API v8
+
+[![Gem Version](https://badge.fury.io/rb/togglv8.svg)](https://badge.fury.io/rb/togglv8) [![Build Status](https://api.travis-ci.org/kanet77/togglv8.svg "Build Status")](https://travis-ci.org/kanet77/togglv8) [![Coverage Status](https://coveralls.io/repos/kanet77/togglv8/badge.svg?branch=master&service=github)](https://coveralls.io/github/kanet77/togglv8?branch=master) [![Code Climate](https://codeclimate.com/github/kanet77/togglv8/badges/gpa.svg)](https://codeclimate.com/github/kanet77/togglv8)
+
+[Toggl](http://www.toggl.com) is a time tracking tool.
+
+[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.
+
+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
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'togglv8'
+```
+
+And then execute:
+
+    $ bundle
+
+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(email, password)     # email & 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>`. 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']
+time_entry   = toggl_api.create_time_entry({
+  'description' => "My awesome workspace time entry",
+  'wid' => workspace_id,
+  'duration' => 1200,
+  '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.
+
+**Note:** Requests are rate-limited. The togglv8 gem will handle a 429 response by pausing for 1 second and trying again, for up to 3 attempts. See [Toggl API docs](https://github.com/toggl/toggl_api_docs#the-api-format):
+
+> For rate limiting we have implemented a Leaky bucket. When a limit has been hit the request will get a HTTP 429 response and it's the task of the client to sleep/wait until bucket is empty. Limits will and can change during time, but a safe window will be 1 request per second. Limiting is applied per api token per IP, meaning two users from the same IP will get their rate allocated separately.
+
+## Debugging
+
+The `TogglV8::API#debug` method determines if debug output is printed to STDOUT. This code snippet demonstrates the debug output.
+
+```ruby
+require 'togglv8'
+
+toggl = TogglV8::API.new
+
+toggl.debug(true)  # or simply toggl.debug
+user1 = toggl.me
+puts "user: #{user1['fullname']}, debug: true"
+
+puts '-'*80
+
+toggl.debug(false)
+user2 = toggl.me
+puts "user: #{user2['fullname']}, debug: false"
+```
+
+## Documentation
+
+Run `rdoc` to generate documentation. Open `doc/index.html` in your browser.
+
+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.
+
+## Contributing
+
+1. Fork it ( https://github.com/kanet77/togglv8/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+Pull Requests that include tests are **much** more likely to be accepted and merged quickly.
+
+## License
+
+Copyright (c) 2013-2016 Tom Kane. Released under the [MIT License](http://opensource.org/licenses/mit-license.php). See [LICENSE.txt](LICENSE.txt) for details.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rake/clean'
+
+CLEAN.add 'coverage'
+CLEAN.add 'doc'
+CLEAN.include 'tmp-*'

data/lib/logging.rb

@@ -0,0 +1,38 @@
+# :nocov:
+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
+# :nocov:

data/lib/reportsv2.rb

@@ -0,0 +1,177 @@
+module TogglV8
+  TOGGL_REPORTS_URL = 'https://api.track.toggl.com/reports/api/v2'
+
+  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::NAME
+
+      username = opts[:api_token]
+      if username.nil?
+        toggl_api_file = opts[:toggl_api_file] || File.join(Dir.home, TOGGL_FILE)
+        if File.exist?(toggl_api_file) then
+          username = IO.read(toggl_api_file)
+        else
+          raise "Expecting one of:\n" +
+            " 1) api_token in file #{toggl_api_file}, or\n" +
+            " 2) parameter: (toggl_api_file), or\n" +
+            " 3) parameter: (api_token), or\n" +
+            "\n\tSee https://github.com/kanet77/togglv8#togglv8reportsv2" +
+            "\n\tand 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: Report
+    #
+    # 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, params)
+      raise "workspace_id is required" if @workspace_id.nil?
+      get "#{type}#{extension}", {
+        :'user_agent' => @user_agent,
+        :'workspace_id' => @workspace_id,
+      }.merge(params)
+    end
+
+    def weekly(extension='', params={})
+      report('weekly', extension, params)
+    end
+
+    def details(extension='', params={})
+      report('details', extension, params)
+    end
+
+    def summary(extension='', params={})
+      report('summary', extension, params)
+    end
+
+    ##
+    # ---------
+    # :section: Write report to file
+    #
+    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, params={})
+      write_report(filename) do |extension|
+        weekly(extension, params)
+      end
+    end
+
+    def write_details(filename, params={})
+      write_report(filename) do |extension|
+        details(extension, params)
+      end
+    end
+
+    def write_summary(filename, params={})
+      write_report(filename) do |extension|
+        summary(extension, params)
+      end
+    end
+
+
+    ##
+    # ---------
+    # :section: Miscellaneous information
+    #
+    def revision
+      get "revision"
+    end
+
+    def index
+      get "index"
+    end
+
+    def env
+      get "env"
+    end
+
+    ##
+    # ---------
+    # :section: Project Dashboard
+    #
+    # Project dashboard returns at-a-glance information for a single project.
+    # This feature is only available with Toggl pro.
+    #
+    # user_agent          : email, or other way to contact client application developer
+    #                       (string, *required*)
+    # workspace_id        : The workspace whose data you want to access
+    #                       (integer, *required*)
+    # project_id          : The project whose data you want to access
+    #                       (integer, *required*)
+    # page                : number of 'tasks_page' you want to fetch
+    #                       (integer, optional)
+    # order_field string  : name/assignee/duration/billable_amount/estimated_seconds
+    # order_desc string   : on/off, on for descending and off for ascending order
+    def project(project_id, params={})
+      raise "workspace_id is required" if @workspace_id.nil?
+      get "project", {
+        :'user_agent' => @user_agent,
+        :'workspace_id' => @workspace_id,
+        :'project_id' => project_id,
+      }.merge(params)
+    end
+
+    ##
+    # ---------
+    # :section: Error (for testing)
+    #
+    # excludes endpoints 'error500' and 'division_by_zero_error'
+    def error400
+      get "error400"
+    end
+  end
+end

data/lib/togglv8/clients.rb

@@ -0,0 +1,37 @@
+module TogglV8
+  class API
+
+    ##
+    # ---------
+    # :section: Clients
+    #
+    # name  : The name of the client (string, required, unique in workspace)
+    # wid   : workspace ID, where the client will be used (integer, required)
+    # notes : Notes for the client (string, not required)
+    # hrate : The hourly rate for this client (float, not required, available only for pro workspaces)
+    # cur   : The name of the client's currency (string, not required, available only for pro workspaces)
+    # at    : timestamp that is sent in the response, indicates the time client was last updated
+
+    def create_client(params)
+      requireParams(params, ['name', 'wid'])
+      post "clients", { 'client' => params }
+    end
+
+    def get_client(client_id)
+      get "clients/#{client_id}"
+    end
+
+    def update_client(client_id, params)
+      put "clients/#{client_id}", { 'client' => params }
+    end
+
+    def delete_client(client_id)
+      delete "clients/#{client_id}"
+    end
+
+    def get_client_projects(client_id, params={})
+      active = params.has_key?('active') ? "?active=#{params['active']}" : ""
+      get "clients/#{client_id}/projects#{active}"
+    end
+  end
+end

data/lib/togglv8/connection.rb

@@ -0,0 +1,99 @@
+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.open(username=nil, password=API_TOKEN, url=nil, opts={})
+      raise 'Missing URL' if url.nil?
+
+      Faraday.new(:url => url, :ssl => {:verify => true}) do |faraday|
+        faraday.adapter Faraday.default_adapter
+        faraday.request :url_encoded
+        faraday.response :logger, Logger.new('faraday.log') if opts[:log]
+        faraday.headers = { "Content-Type" => "application/json" }
+        faraday.request :authorization, :basic, 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'] && !full_resp.headers['warning'].match?(/Deprecation Notice\. Toggl Track API wont be available in this domain after June 2021/)
+      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/dashboard.rb

@@ -0,0 +1,14 @@
+module TogglV8
+  class API
+
+    ##
+    # ---------
+    # :section: Dashboard
+    #
+    # See https://github.com/toggl/toggl_api_docs/blob/master/chapters/dashboard.md
+
+    def dashboard(workspace_id)
+      get "dashboard/#{workspace_id}"
+    end
+  end
+end