togglv9 0.1.0

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tomoya Kabe
+
+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,155 @@
+# Toggl API v9
+
+[![Gem Version](https://badge.fury.io/rb/togglv9-limitusus.svg)](https://badge.fury.io/rb/togglv9-limitusus)
+
+[Toggl](http://www.toggl.com) is a time tracking tool.
+
+[togglv9](/) is a Ruby Wrapper for [Toggl API v9](https://engineering.toggl.com/docs/). It is designed to mirror the Toggl API as closely as possible.
+
+togglv9 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)
+
+NOTE: currently Reports API is not supported yet.
+
+## 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 'togglv9'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install togglv9
+
+## Initialization
+
+### TogglV9::API
+
+TogglV9::API communicates with [Toggl API v9](https://engineering.toggl.com/docs/) and can be initialized in one of three ways.
+
+```ruby
+TogglV9::API.new                      # reads API token from file ~/.toggl
+TogglV9::API.new(api_token)           # explicit API token
+TogglV9::API.new(email, password)     # email & password
+```
+
+### TogglV9::ReportsV2
+
+NOTE: not supported yet. Reports V2 API is already deprecated.
+
+TogglV9::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
+TogglV9::ReportsV2.new                              # reads API token from file ~/.toggl
+TogglV9::ReportsV2.new(toggl_api_file: toggl_file)  # reads API token from toggl_file
+TogglV9::ReportsV2.new(api_token: api_token)        # explicit API token
+```
+
+**Note:** `workspace_id` must be set in order to generate reports.
+
+```ruby
+toggl = TogglV9::API.new
+reports = TogglV9::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 'togglv9'
+require 'json'
+
+toggl_api    = TogglV9::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(workspace_id, {
+  '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               = TogglV9::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 togglv9 gem will handle a 429 response by pausing for 1 second and trying again, for up to 3 attempts. See [Toggl API docs](https://engineering.toggl.com/docs/#generic-responses):
+
+> in case of 429 (Too Many Requests) - back off for a few minutes (you can expect a rate of 1req/sec to be available)
+
+## Debugging
+
+The `TogglV9::API#debug` method determines if debug output is printed to STDOUT. This code snippet demonstrates the debug output.
+
+```ruby
+require 'togglv9'
+
+toggl = TogglV9::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.
+
+## Acknowledgements
+
+- Thanks to [kanet77](https://github.com/kanet77) and its contributers, from which this repository code is based.
+- Thanks to the Toggl team for exposing the API.
+
+## Contributing
+
+1. Fork it ( https://github.com/limitusus/togglv9/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) 2024 Tomoya Kabe.

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 TogglV9
+  TOGGL_REPORTS_URL = 'https://api.track.toggl.com/reports/api/'
+
+  class ReportsV2
+    include TogglV9::Connection
+
+    REPORTS_V2_URL = TOGGL_REPORTS_URL + 'v2/'
+
+    attr_reader :conn
+
+    attr_accessor :workspace_id
+
+    def initialize(opts={})
+      debug(false)
+
+      @user_agent = TogglV9::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/limitusus/togglv9#togglv9reportsv2" +
+            "\n\tand https://github.com/toggl/toggl_api_docs/blob/master/reports.md#authentication"
+        end
+      end
+
+      @conn = TogglV9::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/togglv9/clients.rb

@@ -0,0 +1,38 @@
+module TogglV9
+  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(workspace_id, params)
+      requireParams(params, ['name', 'wid'])
+      post "workspaces/#{workspace_id}/clients", params
+    end
+
+    def get_client(workspace_id, client_id)
+      get "workspaces/#{workspace_id}/clients/#{client_id}"
+    end
+
+    def update_client(workspace_id, client_id, params)
+      put "workspaces/#{workspace_id}/clients/#{client_id}", params
+    end
+
+    def delete_client(workspace_id, client_id)
+      delete "workspaces/#{workspace_id}/clients/#{client_id}"
+    end
+
+    def get_client_projects(workspace_id, client_id, params={})
+      qs = "?clients=#{client_id}"
+      active = params.has_key?('active') ? "&active=#{params['active']}" : ""
+      get "workspaces/#{workspace_id}/projects#{qs}#{active}"
+    end
+  end
+end

data/lib/togglv9/connection.rb

@@ -0,0 +1,105 @@
+require 'faraday'
+require 'oj'
+
+require_relative '../logging'
+
+module TogglV9
+  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.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.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']
+      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 == {}
+      Oj.load(full_resp.body)
+    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 == {}
+      Oj.load(full_resp.body)
+    end
+
+    def patch(resource, data='')
+      resource.gsub!('+', '%2B')
+      full_resp = _call_api(debug_output: lambda { "PATCH #{resource} / #{data}" },
+                  api_call: lambda { self.conn.patch(resource, Oj.dump(data)) } )
+      return {} if full_resp == {}
+      Oj.load(full_resp.body)
+    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/togglv9/dashboard.rb

@@ -0,0 +1,32 @@
+module TogglV9
+  class API
+
+    ##
+    # ---------
+    # :section: Dashboard
+    #
+    # See https://github.com/toggl/toggl_api_docs/blob/master/chapters/dashboard.md
+
+    def dashboard(workspace_id)
+      dashboard = {}
+      dashboard['all_activity']  = all_activity(workspace_id)
+      dashboard['most_active_user'] = most_active_user(workspace_id)
+      dashboard['activity'] = top_activity(workspace_id)
+      dashboard
+    end
+
+    private
+
+    def all_activity(workspace_id)
+      get "workspaces/#{workspace_id}/dashboard/all_activity"
+    end
+
+    def most_active_user(workspace_id)
+      get "workspaces/#{workspace_id}/dashboard/most_active"
+    end
+
+    def top_activity(workspace_id)
+      get "workspaces/#{workspace_id}/dashboard/top_activity"
+    end
+  end
+end

data/lib/togglv9/project_users.rb

@@ -0,0 +1,32 @@
+module TogglV9
+  class API
+
+    ##
+    # ---------
+    # :section: Project Users
+    #
+    # pid      : project ID (integer, required)
+    # uid      : user ID, who is added to the project (integer, required)
+    # wid      : workspace ID, where the project belongs to (integer, not-required, project's workspace id is used)
+    # manager  : admin rights for this project (boolean, default false)
+    # rate     : hourly rate for the project user (float, not-required, only for pro workspaces) in the currency of the project's client or in workspace default currency.
+    # at       : timestamp that is sent in the response, indicates when the project user was last updated
+    # -- Additional fields --
+    # fullname : full name of the user, who is added to the project
+
+    def create_project_user(params)
+      requireParams(params, ['pid', 'uid'])
+      params[:fields] = "fullname"  # for simplicity, always request fullname field
+      post "project_users", { 'project_user' => params }
+    end
+
+    def update_project_user(project_user_id, params)
+      params[:fields] = "fullname"  # for simplicity, always request fullname field
+      put "project_users/#{project_user_id}", { 'project_user' => params }
+    end
+
+    def delete_project_user(project_user_id)
+      delete "project_users/#{project_user_id}"
+    end
+  end
+end