togglv8 0.2.0

data/lib/togglv8/projects.rb

@@ -0,0 +1,111 @@
+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}/project_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)
+      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,53 @@
+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.join(',')}", { 'task' => params }
+    end
+
+    def delete_task(task_id)
+      delete "tasks/#{task_id.join(',')}"
+    end
+
+    # ------------ #
+    # Mass Actions #
+    # ------------ #
+
+    def update_tasks(task_ids, params)
+      put "tasks/#{task_ids.join(',')}", { 'task' => params }
+    end
+
+    def delete_tasks(task_ids)
+      delete "tasks/#{task_ids.join(',')}"
+    end
+
+  end
+end

data/lib/togglv8/time_entries.rb

@@ -0,0 +1,89 @@
+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' 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' 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(start_timestamp=nil, end_timestamp=nil)
+      params = []
+      params.push("start_date=#{iso8601(start_timestamp)}") if !start_timestamp.nil?
+      params.push("end_date=#{iso8601(end_timestamp)}") if !end_timestamp.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)
+      put "time_entries/#{time_entry_ids.join(',')}", { 'time_entry' => params }
+    end
+  end
+end

data/lib/togglv8/users.rb

@@ -0,0 +1,60 @@
+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)
+      # TODO: Reconcile this with get_client_projects
+      # NOTE: response['since'] is discarded
+      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?
+      user['projects'] || {}
+    end
+
+    def my_tags(user=nil)
+      user = me(all=true) if user.nil?
+      user['tags'] || {}
+    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' 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 = "0.2.0"
+end

data/lib/togglv8/workspaces.rb

@@ -0,0 +1,43 @@
+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 leave_workspace(workspace_id)
+      delete "workspaces/#{workspace_id}/leave"
+    end
+  end
+end

data/lib/togglv8.rb

@@ -0,0 +1,137 @@
+require 'faraday'
+require 'oj'
+
+require 'logger'
+require 'awesome_print' # for debug output
+
+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'
+
+# mode: :compat will convert symbols to strings
+Oj.default_options = { mode: :compat }
+
+module TogglV8
+  TOGGL_API_URL = 'https://www.toggl.com/api/'
+
+  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
+
+  #---------#
+  # 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 get(resource)
+      @logger.debug("GET #{resource}")
+      full_resp = self.conn.get(resource)
+      # @logger.ap(full_resp.env, :debug)
+
+      raise 'Too many requests in a given amount of time.' if full_resp.status == 429
+      raise Oj.dump(full_resp.env) unless full_resp.success?
+      return {} if full_resp.body.nil? || full_resp.body == 'null'
+
+      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='')
+      @logger.debug("POST #{resource} / #{data}")
+      full_resp = self.conn.post(resource, Oj.dump(data))
+      # @logger.ap(full_resp.env, :debug)
+
+      raise 'Too many requests in a given amount of time.' if full_resp.status == 429
+      raise Oj.dump(full_resp.env) unless full_resp.success?
+      return {} if full_resp.body.nil? || full_resp.body == 'null'
+
+      resp = Oj.load(full_resp.body)
+      resp['data']
+    end
+
+    def put(resource, data='')
+      @logger.debug("PUT #{resource} / #{data}")
+      full_resp = self.conn.put(resource, Oj.dump(data))
+      # @logger.ap(full_resp.env, :debug)
+
+      raise 'Too many requests in a given amount of time.' if full_resp.status == 429
+      raise Oj.dump(full_resp.env) unless full_resp.success?
+      return {} if full_resp.body.nil? || full_resp.body == 'null'
+
+      resp = Oj.load(full_resp.body)
+      resp['data']
+    end
+
+    def delete(resource)
+      @logger.debug("DELETE #{resource}")
+      full_resp = self.conn.delete(resource)
+      # @logger.ap(full_resp.env, :debug)
+
+      raise 'Too many requests in a given amount of time.' if full_resp.status == 429
+
+      raise Oj.dump(full_resp.env) unless full_resp.success?
+      return {} if full_resp.body.nil? || full_resp.body == 'null'
+
+      full_resp.body
+    end
+
+  end
+
+end

data/spec/lib/togglv8/clients_spec.rb

@@ -0,0 +1,139 @@
+describe 'Clients' do
+  before :all do
+    @toggl = TogglV8::API.new(Testing::API_TOKEN)
+    @workspaces = @toggl.workspaces
+    @workspace_id = @workspaces.first['id']
+  end
+
+  it 'gets {} if there are no clients' do
+    client = @toggl.clients
+    expect(client).to be_empty
+  end
+
+  it 'gets {} if there are no workspace clients' do
+    client = @toggl.clients(@workspace_id)
+    expect(client).to be_empty
+  end
+
+  context 'new client' do
+    before :all do
+      @client = @toggl.create_client({ 'name' => 'new client', 'wid' => @workspace_id })
+      client_ids = @toggl.my_clients.map { |c| c['id'] }
+      expect(client_ids).to eq [ @client['id'] ]
+    end
+
+    after :all do
+      TogglV8SpecHelper.delete_all_clients(@toggl)
+      clients = @toggl.my_clients
+      expect(clients).to be_empty
+    end
+
+    it 'gets a client' do
+      client_ids = @toggl.clients.map { |c| c['id'] }
+      expect(client_ids).to eq [ @client['id'] ]
+    end
+
+    it 'gets a workspace client' do
+      client_ids = @toggl.clients(@workspace_id).map { |c| c['id'] }
+      expect(client_ids).to eq [ @client['id'] ]
+    end
+
+    context 'multiple clients' do
+      before :all do
+        @client2 = @toggl.create_client({ 'name' => 'new client 2', 'wid' => @workspace_id })
+      end
+
+      after :all do
+        @toggl.delete_client(@client2['id'])
+      end
+
+      it 'gets clients' do
+        client_ids = @toggl.clients.map { |c| c['id'] }
+        expect(client_ids).to match_array [ @client['id'], @client2['id'] ]
+      end
+
+      it 'gets workspace clients' do
+        client_ids = @toggl.clients(@workspace_id).map { |c| c['id'] }
+        expect(client_ids).to match_array [ @client['id'], @client2['id'] ]
+      end
+    end
+
+    it 'creates a client' do
+      expect(@client).to_not be nil
+      expect(@client['name']).to eq 'new client'
+      expect(@client['notes']).to eq nil
+      expect(@client['wid']).to eq @workspace_id
+    end
+
+    it 'gets client data' do
+      client = @toggl.get_client(@client['id'])
+      expect(client).to_not be nil
+      expect(client['name']).to eq @client['name']
+      expect(client['wid']).to eq @client['wid']
+      expect(client['notes']).to eq @client['notes']
+      expect(client['at']).to_not be nil
+    end
+
+    context 'client projects' do
+      it 'gets {} if there are no client projects' do
+        projects = @toggl.get_client_projects(@client['id'])
+        expect(projects).to be_empty
+      end
+
+      context 'new client projects' do
+        before :all do
+          @project = @toggl.create_project({ 'name' => 'project', 'wid' => @workspace_id, 'cid' => @client['id'] })
+        end
+
+        after :all do
+          TogglV8SpecHelper.delete_all_projects(@toggl)
+        end
+
+        it 'gets a client project' do
+          projects = @toggl.get_client_projects(@client['id'])
+          project_ids = projects.map { |p| p['id'] }
+          expect(project_ids).to eq [ @project['id'] ]
+        end
+
+        it 'gets multiple client projects' do
+          project2 = @toggl.create_project({ 'name' => 'project2', 'wid' => @workspace_id, 'cid' => @client['id'] })
+
+          projects = @toggl.get_client_projects(@client['id'])
+          project_ids = projects.map { |p| p['id'] }
+          expect(project_ids).to match_array [ @project['id'], project2['id'] ]
+
+          @toggl.delete_project(project2['id'])
+        end
+      end
+    end
+  end
+
+  context 'updated client' do
+    before :each do
+      @client = @toggl.create_client({ 'name' => 'client to update', 'wid' => @workspace_id })
+    end
+
+    after :each do
+      @toggl.delete_client(@client['id'])
+    end
+
+    it 'updates client data' do
+      new_values = {
+        'name' => 'CLIENT-NEW',
+        'notes' => 'NOTES-NEW',
+      }
+
+      client = @toggl.update_client(@client['id'], new_values)
+      expect(client).to include(new_values)
+    end
+
+    it 'updates Pro project data', :pro_account do
+      new_values = {
+        'hrate' => '7.77',
+        'cur' => 'USD',
+      }
+      client = @toggl.update_client(@client['id'], new_values)
+      expect(client).to include(new_values)
+    end
+  end
+end