Class: TogglV8::API

Inherits:
Object
  • Object
show all
Includes:
Connection
Defined in:
lib/togglv8/tags.rb,
lib/togglv8/tasks.rb,
lib/togglv8/users.rb,
lib/togglv8/clients.rb,
lib/togglv8/togglv8.rb,
lib/togglv8/projects.rb,
lib/togglv8/dashboard.rb,
lib/togglv8/workspaces.rb,
lib/togglv8/time_entries.rb,
lib/togglv8/project_users.rb

Constant Summary collapse

TOGGL_API_V8_URL = 
TOGGL_API_URL + 'v8/'

Constants included from Connection

Connection::API_TOKEN, Connection::DELAY_SEC, Connection::MAX_RETRIES, Connection::TOGGL_FILE

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Connection

#_call_api, #delete, #get, open, #post, #put, #requireParams

Methods included from Logging

#debug, included, logger, #logger, logger=

Constructor Details

#initialize(username = nil, password = API_TOKEN, opts = {}) ⇒ API

Returns a new instance of API.



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/togglv8/togglv8.rb', line 22

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)
    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

Instance Attribute Details

#conn ⇒ Object (readonly)

Returns the value of attribute conn.



20
21
22
 
# File 'lib/togglv8/togglv8.rb', line 20

def conn
  @conn
end

Instance Method Details

#clients(workspace_id = nil) ⇒ Object 



17
18
19
20
21
22
23
 
# File 'lib/togglv8/workspaces.rb', line 17

def clients(workspace_id=nil)
  if workspace_id.nil?
    get "clients"
  else
    get "workspaces/#{workspace_id}/clients"
  end
end

#create_client(params) ⇒ Object

: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



15
16
17
18
 
# File 'lib/togglv8/clients.rb', line 15

def create_client(params)
  requireParams(params, ['name', 'wid'])
  post "clients", { 'client' => params }
end

#create_project(params) ⇒ Object

: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



74
75
76
77
 
# File 'lib/togglv8/projects.rb', line 74

def create_project(params)
  requireParams(params, ['name', 'wid'])
  post "projects", { 'project' => params }
end

#create_project_user(params) ⇒ Object

: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



17
18
19
20
21
 
# File 'lib/togglv8/project_users.rb', line 17

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

#create_tag(params) ⇒ Object

:section: Tags

name : The name of the tag (string, required, unique in workspace) wid : workspace ID, where the tag will be used (integer, required)



11
12
13
14
 
# File 'lib/togglv8/tags.rb', line 11

def create_tag(params)
  requireParams(params, ['name', 'wid'])
  post "tags", { 'tag' => params }
end

#create_task(params) ⇒ Object

: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



22
23
24
25
 
# File 'lib/togglv8/tasks.rb', line 22

def create_task(params)
  requireParams(params, ['name', 'pid'])
  post "tasks", { 'task' => params }
end

#create_time_entry(params) ⇒ Object

:section: Time Entries

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



27
28
29
30
31
32
33
34
 
# File 'lib/togglv8/time_entries.rb', line 27

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

#create_user(params) ⇒ Object 



68
69
70
71
72
 
# File 'lib/togglv8/users.rb', line 68

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

#dashboard(workspace_id) ⇒ Object

:section: Dashboard

See github.com/toggl/toggl_api_docs/blob/master/chapters/dashboard.md



10
11
12
 
# File 'lib/togglv8/dashboard.rb', line 10

def dashboard(workspace_id)
  get "dashboard/#{workspace_id}"
end

#delete_client(client_id) ⇒ Object 



28
29
30
 
# File 'lib/togglv8/clients.rb', line 28

def delete_client(client_id)
  delete "clients/#{client_id}"
end

#delete_project(project_id) ⇒ Object

[Delete a project](github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#delete-a-project)



90
91
92
 
# File 'lib/togglv8/projects.rb', line 90

def delete_project(project_id)
  delete "projects/#{project_id}"
end

#delete_project_user(project_user_id) ⇒ Object 



28
29
30
 
# File 'lib/togglv8/project_users.rb', line 28

def delete_project_user(project_user_id)
  delete "project_users/#{project_user_id}"
end

#delete_projects(project_ids) ⇒ Object

[Delete multiple projects](github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#delete-multiple-projects)



107
108
109
110
 
# File 'lib/togglv8/projects.rb', line 107

def delete_projects(project_ids)
  return if project_ids.nil?
  delete "projects/#{project_ids.join(',')}"
end

#delete_tag(tag_id) ⇒ Object 



21
22
23
 
# File 'lib/togglv8/tags.rb', line 21

def delete_tag(tag_id)
  delete "tags/#{tag_id}"
end

#delete_task(task_id) ⇒ Object 



36
37
38
 
# File 'lib/togglv8/tasks.rb', line 36

def delete_task(task_id)
  delete "tasks/#{task_id}"
end

#delete_tasks(task_ids) ⇒ Object 



49
50
51
52
 
# File 'lib/togglv8/tasks.rb', line 49

def delete_tasks(task_ids)
  return if task_ids.nil?
  delete "tasks/#{task_ids.join(',')}"
end

#delete_time_entry(time_entry_id) ⇒ Object 



60
61
62
 
# File 'lib/togglv8/time_entries.rb', line 60

def delete_time_entry(time_entry_id)
  delete "time_entries/#{time_entry_id}"
end

#get_client(client_id) ⇒ Object 



20
21
22
 
# File 'lib/togglv8/clients.rb', line 20

def get_client(client_id)
  get "clients/#{client_id}"
end

#get_client_projects(client_id, params = {}) ⇒ Object 



32
33
34
35
 
# File 'lib/togglv8/clients.rb', line 32

def get_client_projects(client_id, params={})
  active = params.has_key?('active') ? "?active=#{params['active']}" : ""
  get "clients/#{client_id}/projects#{active}"
end

#get_current_time_entry ⇒ Object 



52
53
54
 
# File 'lib/togglv8/time_entries.rb', line 52

def get_current_time_entry
  get "time_entries/current"
end

#get_project(project_id) ⇒ Object

[Get project data](github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#get-project-data)



80
81
82
 
# File 'lib/togglv8/projects.rb', line 80

def get_project(project_id)
  get "projects/#{project_id}"
end

#get_project_tasks(project_id) ⇒ Object

[Get project tasks](github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#get-project-tasks)



100
101
102
 
# File 'lib/togglv8/projects.rb', line 100

def get_project_tasks(project_id)
  get "projects/#{project_id}/tasks"
end

#get_project_users(project_id) ⇒ Object

[Get project users](github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#get-project-users)



95
96
97
 
# File 'lib/togglv8/projects.rb', line 95

def get_project_users(project_id)
  get "projects/#{project_id}/project_users"
end

#get_task(task_id) ⇒ Object 



27
28
29
 
# File 'lib/togglv8/tasks.rb', line 27

def get_task(task_id)
  get "tasks/#{task_id}"
end

#get_time_entries(dates = {}) ⇒ Object 



76
77
78
79
80
81
82
83
 
# File 'lib/togglv8/time_entries.rb', line 76

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

#get_time_entry(time_entry_id) ⇒ Object 



48
49
50
 
# File 'lib/togglv8/time_entries.rb', line 48

def get_time_entry(time_entry_id)
  get "time_entries/#{time_entry_id}"
end

#iso8601(timestamp) ⇒ Object 



64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/togglv8/time_entries.rb', line 64

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

#leave_workspace(workspace_id) ⇒ Object 



43
44
45
 
# File 'lib/togglv8/workspaces.rb', line 43

def leave_workspace(workspace_id)
  delete "workspaces/#{workspace_id}/leave"
end

#me(all = nil) ⇒ Object

: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



23
24
25
26
27
 
# File 'lib/togglv8/users.rb', line 23

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

#my_clients(user = nil) ⇒ Object 



29
30
31
32
 
# File 'lib/togglv8/users.rb', line 29

def my_clients(user=nil)
  user = me(all=true) if user.nil?
  user['clients'] || {}
end

#my_deleted_projects(user = nil) ⇒ Object 



41
42
43
44
45
46
 
# File 'lib/togglv8/users.rb', line 41

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

#my_projects(user = nil) ⇒ Object 



34
35
36
37
38
39
 
# File 'lib/togglv8/users.rb', line 34

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

#my_tags(user = nil) ⇒ Object 



48
49
50
51
 
# File 'lib/togglv8/users.rb', line 48

def my_tags(user=nil)
  user = me(all=true) if user.nil?
  user['tags'] || {}
end

#my_tasks(user = nil) ⇒ Object 



53
54
55
56
 
# File 'lib/togglv8/users.rb', line 53

def my_tasks(user=nil)
  user = me(all=true) if user.nil?
  user['tasks'] || {}
end

#my_time_entries(user = nil) ⇒ Object 



58
59
60
61
 
# File 'lib/togglv8/users.rb', line 58

def my_time_entries(user=nil)
  user = me(all=true) if user.nil?
  user['time_entries'] || {}
end

#my_workspaces(user = nil) ⇒ Object 



63
64
65
66
 
# File 'lib/togglv8/users.rb', line 63

def my_workspaces(user=nil)
  user = me(all=true) if user.nil?
  user['workspaces'] || {}
end

#projects(workspace_id, params = {}) ⇒ Object 



25
26
27
28
 
# File 'lib/togglv8/workspaces.rb', line 25

def projects(workspace_id, params={})
  active = params.has_key?(:active) ? "?active=#{params[:active]}" : ""
  get "workspaces/#{workspace_id}/projects#{active}"
end

#start_time_entry(params) ⇒ Object 



36
37
38
39
40
41
42
 
# File 'lib/togglv8/time_entries.rb', line 36

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

#stop_time_entry(time_entry_id) ⇒ Object 



44
45
46
 
# File 'lib/togglv8/time_entries.rb', line 44

def stop_time_entry(time_entry_id)
  put "time_entries/#{time_entry_id}/stop", {}
end

#tags(workspace_id) ⇒ Object 



39
40
41
 
# File 'lib/togglv8/workspaces.rb', line 39

def tags(workspace_id)
  get "workspaces/#{workspace_id}/tags"
end

#tasks(workspace_id, params = {}) ⇒ Object 



34
35
36
37
 
# File 'lib/togglv8/workspaces.rb', line 34

def tasks(workspace_id, params={})
  active = params.has_key?(:active) ? "?active=#{params[:active]}" : ""
  get "workspaces/#{workspace_id}/tasks#{active}"
end

#update_client(client_id, params) ⇒ Object 



24
25
26
 
# File 'lib/togglv8/clients.rb', line 24

def update_client(client_id, params)
  put "clients/#{client_id}", { 'client' => params }
end

#update_project(project_id, params) ⇒ Object

[Update project data](github.com/toggl/toggl_api_docs/blob/master/chapters/projects.md#update-project-data)



85
86
87
 
# File 'lib/togglv8/projects.rb', line 85

def update_project(project_id, params)
  put "projects/#{project_id}", { 'project' => params }
end

#update_project_user(project_user_id, params) ⇒ Object 



23
24
25
26
 
# File 'lib/togglv8/project_users.rb', line 23

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

#update_tag(tag_id, params) ⇒ Object

ex: update_tag(12345, { :name => “same tame game” })



17
18
19
 
# File 'lib/togglv8/tags.rb', line 17

def update_tag(tag_id, params)
  put "tags/#{tag_id}", { 'tag' => params }
end

#update_task(task_id, params) ⇒ Object

ex: update_task(1894675, { :active => true, :estimated_seconds => 4500, :fields => “done_seconds,uname”})



32
33
34
 
# File 'lib/togglv8/tasks.rb', line 32

def update_task(task_id, params)
  put "tasks/#{task_id}", { 'task' => params }
end

#update_tasks(task_ids, params) ⇒ Object

———— # Mass Actions # ———— #



44
45
46
47
 
# File 'lib/togglv8/tasks.rb', line 44

def update_tasks(task_ids, params)
  return if task_ids.nil?
  put "tasks/#{task_ids.join(',')}", { 'task' => params }
end

#update_time_entries_tags(time_entry_ids, params) ⇒ Object

Example params: =>[‘billed’,‘productive’], ‘tag_action’ => ‘add’ tag_action can be ‘add’ or ‘remove’



87
88
89
90
91
 
# File 'lib/togglv8/time_entries.rb', line 87

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

#update_time_entry(time_entry_id, params) ⇒ Object 



56
57
58
 
# File 'lib/togglv8/time_entries.rb', line 56

def update_time_entry(time_entry_id, params)
  put "time_entries/#{time_entry_id}", { 'time_entry' => params }
end

#users(workspace_id) ⇒ Object 



30
31
32
 
# File 'lib/togglv8/workspaces.rb', line 30

def users(workspace_id)
  get "workspaces/#{workspace_id}/users"
end

#workspaces ⇒ Object

: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



13
14
15
 
# File 'lib/togglv8/workspaces.rb', line 13

def workspaces
  get "workspaces"
end