togglv8-tfl 0.0.1

data/lib/togglv8.rb

@@ -0,0 +1,13 @@
+require_relative 'togglv8/version'
+
+require_relative 'togglv8/connection'
+
+require_relative 'togglv8/togglv8'
+require_relative 'reportsv2'
+
+# :mode => :compat will convert symbols to strings
+Oj.default_options = { :mode => :compat }
+
+module TogglV8
+  NAME = "TogglV8 v#{TogglV8::VERSION}"
+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.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={}, whole_body = false)
+      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') && whole_body == false
+        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

data/lib/togglv8/project_users.rb

@@ -0,0 +1,32 @@
+module TogglV8
+  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

data/lib/togglv8/projects.rb

@@ -0,0 +1,112 @@
+module TogglV8
+  class API
+
+    ##
+    # ---------
+    # :section: Projects
+    #
+    # See Toggl {Projects}[https://github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md]
+    #
+    # name            : The name of the project
+    #                     (string, *required*, unique for client and workspace)
+    # wid             : workspace ID, where the project will be saved
+    #                     (integer, *required*)
+    # cid             : client ID
+    #                     (integer, not required)
+    # active          : whether the project is archived or not
+    #                     (boolean, by default true)
+    # is_private      : whether project is accessible for only project users or for all workspace users
+    #                     (boolean, default true)
+    # template        : whether the project can be used as a template
+    #                     (boolean, not required)
+    # template_id     : id of the template project used on current project's creation
+    # billable        : whether the project is billable or not
+    #                     (boolean, default true, available only for pro workspaces)
+    # auto_estimates  : whether the estimated hours is calculated based on task estimations or is fixed manually
+    #                   (boolean, default false, not required, premium functionality)
+    # estimated_hours : if auto_estimates is true then the sum of task estimations is returned, otherwise user inserted hours
+    #                     (integer, not required, premium functionality)
+    # at              : timestamp that is sent in the response for PUT, indicates the time task was last updated
+    # color           : id of the color selected for the project
+    # rate            : hourly rate of the project
+    #                     (float, not required, premium functionality)
+    # created_at      : timestamp indicating when the project was created (UTC time), read-only
+    # ---------
+
+    ##
+    # :category: Projects
+    #
+    # Public: Create a new project
+    #
+    # params - The Hash used to create the project (default: {})
+    #          :name            - The name of the project (string, required, unique for client and workspace)
+    #          :wid             - workspace ID, where the project will be saved (integer, required)
+    #          :cid             - client ID (integer, not required)
+    #          :active          - whether the project is archived or not (boolean, by default true)
+    #          :is_private      - whether project is accessible for only project users or for all workspace users (boolean, default true)
+    #          :template        - whether the project can be used as a template (boolean, not required)
+    #          :template_id     - id of the template project used on current project's creation
+    #          :billable        - whether the project is billable or not (boolean, default true, available only for pro workspaces)
+    #          :auto_estimates  - whether the estimated hours is calculated based on task estimations or is fixed manually (boolean, default false, not required, premium functionality)
+    #          :estimated_hours - if auto_estimates is true then the sum of task estimations is returned, otherwise user inserted hours (integer, not required, premium functionality)
+    #          :at              - timestamp that is sent in the response for PUT, indicates the time task was last updated
+    #          :color           - id of the color selected for the project
+    #          :rate            - hourly rate of the project (float, not required, premium functionality)
+    #          :created_at      - timestamp indicating when the project was created (UTC time), read-only
+    #
+    # Examples
+    #
+    #     toggl.create_project({ :name => 'My project', :wid => 1060392 })
+    #     => {"id"=>10918774,
+    #      "wid"=>1060392,
+    #      "name"=>"project5",
+    #      "billable"=>false,
+    #      "is_private"=>true,
+    #      "active"=>true,
+    #      "template"=>false,
+    #      "at"=>"2015-08-18T10:03:51+00:00",
+    #      "color"=>"5",
+    #      "auto_estimates"=>false}
+    #
+    # Returns a +Hash+ representing the newly created Project.
+    #
+    # See Toggl {Create Project}[https://github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#create-project]
+    def create_project(params)
+      requireParams(params, ['name', 'wid'])
+      post "projects", { 'project' => params }
+    end
+
+    # [Get project data](https://github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#get-project-data)
+    def get_project(project_id)
+      get "projects/#{project_id}"
+    end
+
+    # [Update project data](https://github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#update-project-data)
+    def update_project(project_id, params)
+      put "projects/#{project_id}", { 'project' => params }
+    end
+
+    # [Delete a project](https://github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#delete-a-project)
+    def delete_project(project_id)
+      delete "projects/#{project_id}"
+    end
+
+    # [Get project users](https://github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#get-project-users)
+    def get_project_users(project_id)
+      get "projects/#{project_id}/project_users"
+    end
+
+    # [Get project tasks](https://github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#get-project-tasks)
+    def get_project_tasks(project_id)
+      get "projects/#{project_id}/tasks"
+    end
+
+    # [Get workspace projects](https://github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#get-workspace-projects)
+
+    # [Delete multiple projects](https://github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#delete-multiple-projects)
+    def delete_projects(project_ids)
+      return if project_ids.nil?
+      delete "projects/#{project_ids.join(',')}"
+    end
+  end
+end

data/lib/togglv8/tags.rb

@@ -0,0 +1,25 @@
+module TogglV8
+  class API
+
+    ##
+    # ---------
+    # :section: Tags
+    #
+    # name : The name of the tag (string, required, unique in workspace)
+    # wid  : workspace ID, where the tag will be used (integer, required)
+
+    def create_tag(params)
+      requireParams(params, ['name', 'wid'])
+      post "tags", { 'tag' => params }
+    end
+
+    # ex: update_tag(12345, { :name => "same tame game" })
+    def update_tag(tag_id, params)
+      put "tags/#{tag_id}", { 'tag' => params }
+    end
+
+    def delete_tag(tag_id)
+      delete "tags/#{tag_id}"
+    end
+  end
+end

data/lib/togglv8/tasks.rb

@@ -0,0 +1,55 @@
+module TogglV8
+  class API
+
+    ##
+    # ---------
+    # :section: Tasks
+    #
+    # NOTE: Tasks are available only for pro workspaces.
+    #
+    # name              : The name of the task (string, required, unique in project)
+    # pid               : project ID for the task (integer, required)
+    # wid               : workspace ID, where the task will be saved
+    #                     (integer, project's workspace id is used when not supplied)
+    # uid               : user ID, to whom the task is assigned to (integer, not required)
+    # estimated_seconds : estimated duration of task in seconds (integer, not required)
+    # active            : whether the task is done or not (boolean, by default true)
+    # at                : timestamp that is sent in the response for PUT, indicates the time task was last updated
+    # -- Additional fields --
+    # done_seconds      : duration (in seconds) of all the time entries registered for this task
+    # uname             : full name of the person to whom the task is assigned to
+
+    def create_task(params)
+      requireParams(params, ['name', 'pid'])
+      post "tasks", { 'task' => params }
+    end
+
+    def get_task(task_id)
+      get "tasks/#{task_id}"
+    end
+
+    # ex: update_task(1894675, { :active => true, :estimated_seconds => 4500, :fields => "done_seconds,uname"})
+    def update_task(task_id, params)
+      put "tasks/#{task_id}", { 'task' => params }
+    end
+
+    def delete_task(task_id)
+      delete "tasks/#{task_id}"
+    end
+
+    # ------------ #
+    # Mass Actions #
+    # ------------ #
+
+    def update_tasks(task_ids, params)
+      return if task_ids.nil?
+      put "tasks/#{task_ids.join(',')}", { 'task' => params }
+    end
+
+    def delete_tasks(task_ids)
+      return if task_ids.nil?
+      delete "tasks/#{task_ids.join(',')}"
+    end
+
+  end
+end

data/lib/togglv8/time_entries.rb

@@ -0,0 +1,93 @@
+module TogglV8
+  class API
+
+    ##
+    # ---------
+    # :section: Time Entries
+    #
+    # https://github.com/toggl/toggl_api_docs/blob/master/chapters/time_entries.md
+    #
+    # description  : (string, strongly suggested to be used)
+    # wid          : workspace ID (integer, required if pid or tid not supplied)
+    # pid          : project ID (integer, not required)
+    # tid          : task ID (integer, not required)
+    # billable     : (boolean, not required, default false, available for pro workspaces)
+    # start        : time entry start time (string, required, ISO 8601 date and time)
+    # stop         : time entry stop time (string, not required, ISO 8601 date and time)
+    # duration     : time entry duration in seconds. If the time entry is currently running,
+    #                the duration attribute contains a negative value,
+    #                denoting the start of the time entry in seconds since epoch (Jan 1 1970).
+    #                The correct duration can be calculated as current_time + duration,
+    #                where current_time is the current time in seconds since epoch. (integer, required)
+    # created_with : the name of your client app (string, required)
+    # tags         : a list of tag names (array of strings, not required)
+    # duronly      : should Toggl show the start and stop time of this time entry? (boolean, not required)
+    # at           : timestamp that is sent in the response, indicates the time item was last updated
+
+    def create_time_entry(params)
+      params['created_with'] = TogglV8::NAME unless params.has_key?('created_with')
+      requireParams(params, ['start', 'duration', 'created_with'])
+      if !params.has_key?('wid') and !params.has_key?('pid') and !params.has_key?('tid') then
+        raise ArgumentError, "one of params['wid'], params['pid'], params['tid'] is required"
+      end
+      post "time_entries", { 'time_entry' => params }
+    end
+
+    def start_time_entry(params)
+      params['created_with'] = TogglV8::NAME unless params.has_key?('created_with')
+      if !params.has_key?('wid') and !params.has_key?('pid') and !params.has_key?('tid') then
+        raise ArgumentError, "one of params['wid'], params['pid'], params['tid'] is required"
+      end
+      post "time_entries/start", { 'time_entry' => params }
+    end
+
+    def stop_time_entry(time_entry_id)
+      put "time_entries/#{time_entry_id}/stop", {}
+    end
+
+    def get_time_entry(time_entry_id)
+      get "time_entries/#{time_entry_id}"
+    end
+
+    def get_current_time_entry
+      get "time_entries/current"
+    end
+
+    def update_time_entry(time_entry_id, params)
+      put "time_entries/#{time_entry_id}", { 'time_entry' => params }
+    end
+
+    def delete_time_entry(time_entry_id)
+      delete "time_entries/#{time_entry_id}"
+    end
+
+    def iso8601(timestamp)
+      return nil if timestamp.nil?
+      if timestamp.is_a?(DateTime) or timestamp.is_a?(Date)
+        formatted_ts = timestamp.iso8601
+      elsif timestamp.is_a?(String)
+        formatted_ts = DateTime.parse(timestamp).iso8601
+      else
+        raise ArgumentError, "Can't convert #{timestamp.class} to ISO-8601 Date/Time"
+      end
+      return formatted_ts.sub('+00:00', 'Z')
+    end
+
+    def get_time_entries(dates = {})
+      start_date = dates[:start_date]
+      end_date = dates[:end_date]
+      params = []
+      params.push("start_date=#{iso8601(start_date)}") unless start_date.nil?
+      params.push("end_date=#{iso8601(end_date)}") unless end_date.nil?
+      get "time_entries%s" % [params.empty? ? "" : "?#{params.join('&')}"]
+    end
+
+    # Example params: {'tags' =>['billed','productive'], 'tag_action' => 'add'}
+    # tag_action can be 'add' or 'remove'
+    def update_time_entries_tags(time_entry_ids, params)
+      return if time_entry_ids.nil?
+      requireParams(params, ['tags', 'tag_action'])
+      put "time_entries/#{time_entry_ids.join(',')}", { 'time_entry' => params }
+    end
+  end
+end