togglv8-ng 1.4.0

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,114 @@
+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
+
+    # TEMPORARY FIXED version of API issue
+    # see https://github.com/toggl/toggl_api_docs/issues/20 for more info
+    def update_time_entries_tags_fixed(time_entry_ids, params)
+      time_entries = update_time_entries_tags(time_entry_ids, params)
+      return time_entries if params['tag_action'] == 'add'
+
+      time_entries_for_removing_all_tags_ids = []
+      [].push(time_entries).flatten.map! do |time_entry|
+        unless time_entry['tags'].nil?
+          time_entry['tags'] = time_entry['tags'] - params['tags']
+          time_entries_for_removing_all_tags_ids << time_entry['id'] if time_entry['tags'].empty?
+        end
+        time_entry
+      end
+
+      remove_params = {'tags' => []}
+      put "time_entries/#{time_entries_for_removing_all_tags_ids.join(',')}", { 'time_entry' => remove_params } unless time_entries_for_removing_all_tags_ids.empty?
+
+      time_entries
+    end
+  end
+end

data/lib/togglv8/togglv8.rb

@@ -0,0 +1,55 @@
+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://api.track.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)
+      if username.nil? && password == API_TOKEN
+        toggl_api_file = File.join(Dir.home, TOGGL_FILE)
+        # logger.debug("toggl_api_file = #{toggl_api_file}")
+        if File.exist?(toggl_api_file) then
+          username = IO.read(toggl_api_file).strip
+        else
+          raise "Expecting one of:\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/kanet77/togglv8#togglv8api" +
+            "\n\tand https://github.com/toggl/toggl_api_docs/blob/master/chapters/authentication.md"
+        end
+      end
+
+      @conn = TogglV8::Connection.open(username, password,
+                TOGGL_API_V8_URL, opts)
+    end
+  end
+end
+
+
+
+
+
+
+
+
+
+
+
+

data/lib/togglv8/users.rb

@@ -0,0 +1,74 @@
+module TogglV8
+  class API
+
+    ##
+    # ---------
+    # :section: Users
+    #
+    # api_token                 : (string)
+    # default_wid               : default workspace id (integer)
+    # email                     : (string)
+    # jquery_timeofday_format   : (string)
+    # jquery_date_format        : (string)
+    # timeofday_format          : (string)
+    # date_format               : (string)
+    # store_start_and_stop_time : whether start and stop time are saved on time entry (boolean)
+    # beginning_of_week         : (integer, Sunday=0)
+    # language                  : user's language (string)
+    # image_url                 : url with the user's profile picture(string)
+    # sidebar_piechart          : should a piechart be shown on the sidebar (boolean)
+    # at                        : timestamp of last changes
+    # new_blog_post             : an object with toggl blog post title and link
+
+    def me(all=nil)
+      # NOTE: response['since'] is discarded because it is outside response['data']
+      #       (See TogglV8::API#get in lib/togglv8.rb)
+      get "me%s" % [all.nil? ? "" : "?with_related_data=#{all}"]
+    end
+
+    def my_clients(user=nil)
+      user = me(all=true) if user.nil?
+      user['clients'] || {}
+    end
+
+    def my_projects(user=nil)
+      user = me(all=true) if user.nil?
+      return {} unless user['projects']
+      projects = user['projects']
+      projects.delete_if { |p| p['server_deleted_at'] }
+    end
+
+    def my_deleted_projects(user=nil)
+      user = me(all=true) if user.nil?
+      return {} unless user['projects']
+      projects = user['projects']
+      projects.keep_if { |p| p['server_deleted_at'] }
+    end
+
+    def my_tags(user=nil)
+      user = me(all=true) if user.nil?
+      user['tags'] || {}
+    end
+
+    def my_tasks(user=nil)
+      user = me(all=true) if user.nil?
+      user['tasks'] || {}
+    end
+
+    def my_time_entries(user=nil)
+      user = me(all=true) if user.nil?
+      user['time_entries'] || {}
+    end
+
+    def my_workspaces(user=nil)
+      user = me(all=true) if user.nil?
+      user['workspaces'] || {}
+    end
+
+    def create_user(params)
+      params['created_with'] = TogglV8::NAME unless params.has_key?('created_with')
+      requireParams(params, ['email', 'password', 'timezone', 'created_with'])
+      post "signups", { 'user' => params }
+    end
+  end
+end

data/lib/togglv8/version.rb

@@ -0,0 +1,4 @@
+module TogglV8
+  # :section:
+  VERSION = "1.4.0"
+end

data/lib/togglv8/workspaces.rb

@@ -0,0 +1,47 @@
+module TogglV8
+  class API
+
+    ##
+    # ---------
+    # :section: Workspaces
+    #
+    # name    : (string, required)
+    # premium : If it's a pro workspace or not.
+    #           Shows if someone is paying for the workspace or not (boolean, not required)
+    # at      : timestamp that is sent in the response, indicates the time item was last updated
+
+    def workspaces
+      get "workspaces"
+    end
+
+    def clients(workspace_id=nil)
+      if workspace_id.nil?
+        get "clients"
+      else
+        get "workspaces/#{workspace_id}/clients"
+      end
+    end
+
+    def projects(workspace_id, params={})
+      active = params.has_key?(:active) ? "?active=#{params[:active]}" : ""
+      get "workspaces/#{workspace_id}/projects#{active}"
+    end
+
+    def users(workspace_id)
+      get "workspaces/#{workspace_id}/users"
+    end
+
+    def tasks(workspace_id, params={})
+      active = params.has_key?(:active) ? "?active=#{params[:active]}" : ""
+      get "workspaces/#{workspace_id}/tasks#{active}"
+    end
+
+    def tags(workspace_id)
+      get "workspaces/#{workspace_id}/tags"
+    end
+
+    def leave_workspace(workspace_id)
+      delete "workspaces/#{workspace_id}/leave"
+    end
+  end
+end

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