Class: Toggl

Inherits:
Object
  • Object
show all
Defined in:
lib/git-pivotal-tracker-integration/util/togglV8.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(username = nil, password = 'api_token', debug = nil) ⇒ Toggl

Returns a new instance of Toggl.



20
21
22
23
24
25
26
27
28
29
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 20

def initialize(username=nil, password='api_token', debug=nil)
  self.debug_on(debug) if !debug.nil?
  if (password.to_s == 'api_token' && username.to_s == '')
    toggl_api_file = self.toggl_file
    username = IO.read(toggl_api_file)

  end

  @conn = connection(username, password)
end

Instance Attribute Details

#conn ⇒ Object

Returns the value of attribute conn.



18
19
20
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 18

def conn
  @conn
end

#debug ⇒ Object

Returns the value of attribute debug.



18
19
20
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 18

def debug
  @debug
end

Instance Method Details

#checkParams(params, fields = []) ⇒ Object

Raises:

  • (ArgumentError) 


58
59
60
61
62
63
64
65
66
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 58

def checkParams(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

#clients(workspace = nil) ⇒ Object 



360
361
362
363
364
365
366
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 360

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

#connection(username, password) ⇒ Object 



43
44
45
46
47
48
49
50
51
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 43

def connection(username, password)
  Faraday.new(url: 'https://www.toggl.com/api/v8', :ssl => {:verify => false}) do |faraday|
    faraday.request :url_encoded
    faraday.response :logger, Logger.new('faraday.log')
    faraday.adapter Faraday.default_adapter
    faraday.headers = {"Content-Type" => "application/json"}
    faraday.basic_auth username, password
  end
end

#create_client(params) ⇒ Object

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



108
109
110
111
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 108

def create_client(params)
  checkParams(params, [:name, :wid])
  post "clients", {client: params}
end

#create_project(params) ⇒ Object

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) at : timestamp that is sent in the response for PUT, indicates the time task was last updated – Undocumented – color : number (in the range 0-23?)



147
148
149
150
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 147

def create_project(params)
  checkParams(params, [:name, :wid])
  post "projects", {project: params}
end

#create_project_user(params) ⇒ Object

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



193
194
195
196
197
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 193

def create_project_user(params)
  checkParams(params, [:pid, :uid])
  params[:fields] = "fullname"  # for simplicity, always request fullname field
  post "project_users", {project_user: params}
end

#create_tag(params) ⇒ Object

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



215
216
217
218
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 215

def create_tag(params)
  checkParams(params, [:name, :wid])
  post "tags", {tag: params}
end

#create_task(params) ⇒ Object

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



244
245
246
247
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 244

def create_task(params)
  checkParams(params, [:name, :pid])
  post "tasks", {task: params}
end

#create_time_entry(params) ⇒ Object

description : (string, required) 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



279
280
281
282
283
284
285
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 279

def create_time_entry(params)
  checkParams(params, [:description, :start, :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

#debug_on(debug = true) ⇒ Object 



53
54
55
56
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 53

def debug_on(debug=true)
  puts "debugging is %s" % [debug ? "ON" : "OFF"]
  @debug = debug
end

#delete_client(client_id) ⇒ Object 



121
122
123
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 121

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

#delete_project_user(project_user_id) ⇒ Object 



204
205
206
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 204

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

#delete_tag(tag_id) ⇒ Object 



225
226
227
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 225

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

#delete_task(*task_id) ⇒ Object 



258
259
260
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 258

def delete_task(*task_id)
  delete "tasks/#{task_id.join(',')}"
end

#delete_time_entry(time_entry_id) ⇒ Object 



306
307
308
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 306

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

#get_client(client_id) ⇒ Object 



113
114
115
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 113

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

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



125
126
127
128
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 125

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

#get_project(project_id) ⇒ Object 



152
153
154
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 152

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

#get_project_task_with_name(project_id, task_name) ⇒ Object 



168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 168

def get_project_task_with_name(project_id, task_name)
  task = nil
  project_tasks = get_project_tasks(project_id) || []
  project_tasks.each { |a_task|
    a_task_name = "#{a_task["name"]}"
    if (a_task_name.include?task_name)
      task = a_task
      break
    end
  }
task
end

#get_project_tasks(project_id) ⇒ Object 



164
165
166
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 164

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

#get_project_users(project_id) ⇒ Object 



160
161
162
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 160

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

#get_task(task_id) ⇒ Object 



249
250
251
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 249

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

#get_time_entries(start_date = nil, end_date = nil) ⇒ Object 



322
323
324
325
326
327
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 322

def get_time_entries(start_date=nil, end_date=nil)
  params = []
  params.push("start_date=#{iso8601(start_date)}") if !start_date.nil?
  params.push("end_date=#{iso8601(end_date)}") if !end_date.nil?
  get "time_entries%s" % [params.empty? ? "" : "?#{params.join('&')}"]
end

#get_time_entry(time_entry_id) ⇒ Object 



298
299
300
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 298

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

#iso8601(date) ⇒ Object 



310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 310

def iso8601(date)
  return nil if date.nil?
  if date.is_a?(Time) or date.is_a?(Date)
    iso = date.iso8601
  elsif date.is_a?(String)
    iso =  DateTime.parse(date).iso8601
  else
    raise ArgumentError, "Can't convert #{date.class} to ISO-8601 Date/Time"
  end
  return Faraday::Utils.escape(iso)
end

#me(all = nil) ⇒ Object

———-# — Me —# ———-#



72
73
74
75
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 72

def me(all=nil)
  # TODO: Reconcile this with get_client_projects
  res = get "me%s" % [all.nil? ? "" : "?with_related_data=#{all}"]
end

#my_clients(user) ⇒ Object 



77
78
79
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 77

def my_clients(user)
  user['projects']
end

#my_projects(user) ⇒ Object 



81
82
83
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 81

def my_projects(user)
  user['projects']
end

#my_tags(user) ⇒ Object 



85
86
87
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 85

def my_tags(user)
  user['tags']
end

#my_time_entries(user) ⇒ Object 



89
90
91
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 89

def my_time_entries(user)
  user['time_entries']
end

#my_workspaces(user) ⇒ Object 



93
94
95
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 93

def my_workspaces(user)
  user['workspaces']
end

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



368
369
370
371
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 368

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

#start_time_entry(params) ⇒ Object 



287
288
289
290
291
292
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 287

def start_time_entry(params)
  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 



294
295
296
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 294

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

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



377
378
379
380
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 377

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

#toggl_file ⇒ Object 



31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 31

def toggl_file
  t_file = ENV['HOME']+'/.toggl'
  if !FileTest.exist?(t_file) then
    puts "\n\nIt looks like this is the first time you have used Toggl on this machine.\n"
    t_API_key = ask("Please enter your Toggl API key:")
    output = File.open( t_file, "w")
    output << t_API_key
    output.close
  end

  t_file
end

#update_client(client_id, params) ⇒ Object 



117
118
119
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 117

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

#update_project(project_id, params) ⇒ Object 



156
157
158
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 156

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

#update_project_user(project_user_id, params) ⇒ Object 



199
200
201
202
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 199

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, “same tame game”)



221
222
223
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 221

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

#update_task(*task_id, params) ⇒ Object

ex: update_task(1894675, true, estimated_seconds: 4500, fields: “done_seconds,uname”)



254
255
256
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 254

def update_task(*task_id, params)
  put "tasks/#{task_id.join(',')}", {task: params}
end

#update_time_entry(time_entry_id, params) ⇒ Object 



302
303
304
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 302

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

#users(workspace) ⇒ Object 



373
374
375
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 373

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

#workspaces ⇒ Object

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



356
357
358
 
# File 'lib/git-pivotal-tracker-integration/util/togglV8.rb', line 356

def workspaces
  get "workspaces"
end