togglv8 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a10237427eb728d8536f6276c84e0e83a051695c
+  data.tar.gz: bb81c9c5d1c9a2f1d17b943eefdc1682565da2eb
+SHA512:
+  metadata.gz: 944c4db8f611b45f210a53aba3ad3de9b5ea2c1237d982e4f06fe24637c0e5c6caaacf96ad936d59255d7bc8cb3e03e76a6d66851fbd33a205105f1d9e5cd23b
+  data.tar.gz: a5b4cdc752d55441db098753d4f578d68f7888118686dad90f1fbf79991fab5ffc80f4998ed0d07df81234176077f1511300cb472ab78e41c1123717e0dedb13

data/.coveralls.yml

@@ -0,0 +1 @@
+repo_token: D1ZrNoAoVUgrr8B1KvO8ky8jUpFftVJfH

data/.gitignore

@@ -0,0 +1,4 @@
+Gemfile.lock
+coverage/
+doc/
+pkg/

data/.rdoc_options

@@ -0,0 +1,23 @@
+--- !ruby/object:RDoc::Options
+encoding: UTF-8
+static_path: []
+rdoc_include:
+- "."
+- "/Users/tk/src/togglv8"
+charset: UTF-8
+exclude:
+hyperlink_all: false
+line_numbers: false
+locale:
+locale_dir: locale
+locale_name:
+main_page: README.md
+markup: tomdoc
+output_decoration: true
+page_dir:
+show_hash: false
+tab_width: 8
+template_stylesheets: []
+title: Toggl V8
+visibility: :protected
+webcvs:

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+rvm:
+  - ruby-head
+script: bundle exec rspec
+cache: bundler
+branches:
+  only:
+    - master
+addons:
+  code_climate:
+    repo_token: eb44970f9efc497fb68c6ec1ce051dea530776b6a5bbe75e57734625f761ac86

data/API calls.md

@@ -0,0 +1,330 @@
+# Toggl v8 API calls
+
+These API calls with [curl](http://curl.haxx.se/) were useful when prototyping togglv8.
+
+The calls have since been converted to use [resty](https://github.com/micha/resty) (a wrapper for curl). They are included here only for reference.
+
+See [Toggl API Documentation](https://github.com/toggl/toggl_api_docs) for more authoritative, comprehensive, and up-to-date information.
+
+As of 2013-08-11, the calls listed here cover almost the entire [Toggl API](https://github.com/toggl/toggl_api_docs/blob/master/toggl_api.md) section. The following calls are not yet supported by [togglv8](/):
+* [Add multiple users to a project](/API%20calls.md#add-multiple-users-to-a-project)
+* [Update multiple project users](/API%20calls.md#update-multiple-project-users)
+* [Delete multiple project users](/API%20calls.md#delete-multiple-project-users)
+* [Sign up new user](/API%20calls.md#sign-up-new-user) (Will increase the cost of your Toggl account.)
+* [Invite users to workspace](/API%20calls.md#invite-users-to-workspace)
+* [Delete workspace user](/API%20calls.md#delete-workspace-user)
+* [Get workspace users for a workspace](/API%20calls.md#get-workspace-users-for-a-workspace)
+
+# Authentication
+
+Toggl API uses Basic Auth. Resty is initialized with basic auth info (-u), as well as headers (-H).
+
+### HTTP Basic Auth with API token
+The user API Token for an account is available under [My Profile](https://www.toggl.com/user/edit) after logging into [Toggl.com](https://www.toggl.com).
+
+When using an API Token, the user is your API Token and the password is "api_token".
+```
+resty https://www.toggl.com/api/v8 -u 1971800d4d82861d8f2c1651fea4d212:api_token -H "Content-type: application/json"
+```
+
+### (Alternative method) HTTP Basic Auth with e-mail and password
+It is also possible to use your email address and Toggl password.
+```
+resty https://www.toggl.com/api/v8 -u your.email@example.com:SuperSecretPassword -H "Content-type: application/json"
+```
+
+# Displaying JSON
+It is helpful to use a JSON parsing tool such as [Jazor](https://github.com/mconigliaro/jazor).
+
+For example, ```GET /me | jazor -c``` outputs
+
+```
+{
+  since: 1370938972,
+  data: {
+    id: {<user_id>},
+    api_token: "<api_token>",
+    default_wid: <wid>,
+    email: "<email_address>",
+    fullname: "<fullname>",
+    jquery_timeofday_format: H:i,
+    jquery_date_format: "m/d/Y",
+    timeofday_format: H:mm,
+    date_format: "MM/DD/YYYY",
+    store_start_and_stop_time: true,
+    beginning_of_week: 1,
+    language: "en_US",
+    image_url: https://www.toggl.com/system/avatars/<image.jpg>,
+    sidebar_piechart: false,
+    at: "2013-06-11T07:00:44+00:00",
+    created_at: "2012-08-01T12:41:56+00:00",
+    retention: 9,
+    record_timeline: true,
+    render_timeline: true,
+    timeline_enabled: true,
+    timeline_experiment: true,
+    manual_mode: true,
+    new_blog_post: {
+    },
+    invitation: {
+    }
+  }
+}
+```
+
+rather than
+
+```
+{"since":1370938972,"data":{"id":<user_id>},"api_token":"<api_token>","default_wid":<wid>,"email":"<email_address>","fullname":"<fullname>","jquery_timeofday_format":"H:i","jquery_date_format":"m/d/Y","timeofday_format":"H:mm","date_format":"MM/DD/YYYY","store_start_and_stop_time":true,"beginning_of_week":1,"language":"en_US","image_url":"https://www.toggl.com/system/avatars/<image.jpg>","sidebar_piechart":false,"at":"2013-06-11T07:00:44+00:00","created_at":"2012-08-01T12:41:56+00:00","retention":9,"record_timeline":true,"render_timeline":true,"timeline_enabled":true,"timeline_experiment":true,"manual_mode":true,"new_blog_post":{},"invitation":{}}}
+```
+
+---
+
+# Clients
+
+### Create client
+```
+POST /clients -d '{"client":{"name":"Very Big Company","wid":282224}}'
+```
+
+### Read client
+```
+GET /clients/1101632
+```
+
+### Update client
+```
+PUT /clients/1150638 -d '{"client":{"notes":"this client must go!"}}'
+```
+
+### Delete client
+```
+DELETE /clients/1150758
+```
+
+### Get clients visible to user
+```
+GET /clients
+```
+
+### Get client projects
+```
+GET /clients/1150488/projects
+```
+
+# Projects
+
+### Create project
+```
+POST /projects -d '{"project":{"name":"TEST project","wid":282224,"is_private":true}}'
+```
+
+### Read project
+```
+GET /projects/2882160
+```
+
+### Update project
+```
+PUT /projects/2931253 -d '{"project":{"name":"Changed the name","is_private":false,"template":true}}'
+```
+
+### Get project users
+```
+GET /projects/2883126/project_users
+```
+
+# Project users
+
+### Create project user
+```
+POST /project_users -d '{"project_user":{"pid":2931296,"uid":509726,"rate":30.0,"manager":true}}'
+```
+
+### Update project user
+```
+PUT /project_users/8310314 -d '{"project_user":{"manager":false,"rate":15,"fields":"fullname"}}'
+```
+
+### Delete project user
+```
+DELETE /project_users/8310314
+```
+### Add multiple users to a project
+**Note:** Not yet supported by [togglv8](/)
+
+### Update multiple project users
+**Note:** Not yet supported by [togglv8](/)
+
+### Delete multiple project users
+**Note:** Not yet supported by [togglv8](/)
+
+# Tags
+
+### Create tag
+```
+POST /tags -d '{"tag":{"name":"tag"}}'
+```
+
+### Update tag
+```
+PUT /tags/294414 -d '{"tag":{"name":"taggggg"}}'
+```
+
+### Delete tag
+```
+DELETE /tags/294414
+```
+
+# Tasks
+
+### Create task
+```
+POST /tasks -d '{"task":{"name":"A new task","pid":2883129}}'
+```
+
+### Get task details
+```
+GET /tasks/1894675
+```
+
+### Update task
+```
+PUT /tasks/1894675 -d '{"task":{"id": 1894675, "active": true, "estimated_seconds": 7200, "fields": "done_seconds,uname"}}'
+```
+
+### Delete task
+```
+DELETE /tasks/1893464
+```
+
+### Update multiple tasks
+```
+PUT /tasks/1894758,1894751 -d '{"task":{"active":false,"fields":"done_seconds,uname"}}'
+```
+
+### Delete multiple Tasks
+```
+DELETE /tasks/1922656,1922683,1922684
+```
+
+# Time entries
+
+### Create time entry
+```
+POST /time_entries -d '{"time_entry":{"description":"Meeting with possible clients","tags":["billed"],"duration":1200,"start":"2013-03-05T07:58:58.000Z","pid":2931296}}'
+```
+
+### Get time entry details
+```
+GET /time_entries/77628973
+```
+
+### Start a time entry
+```
+POST /time_entries/start -d '{"time_entry":{"description":"New time entry","wid":282224}}'
+```
+
+### Stop a time entry
+```
+PUT /time_entries/86229778/stop
+```
+
+### Update time entry
+```
+PUT /time_entries/86229778 -d '{"time_entry":{"description":"Renamed new time entry","duration":180}}'
+```
+
+### Delete time entry
+```
+DELETE /time_entries/86229778
+```
+
+### Get time entries started in a specific time range
+**Note:**
+
+- `start_date` and `end_date` are in [ISO 8601 date and time format](http://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations), (e.g. "2013-03-10T15:42:46+02:00")
+- It is necessary to use the encoded value %2B for '+' in order to avoid JSON parsing error. (Using %3A for ':' is not strictly necessary.)
+
+```
+GET /time_entries -q 'start_date=2013-05-22T15:42:46%2B02:00&end_date=2013-05-22T16:42:46%2B02:00'
+```
+
+```
+GET /time_entries -q 'start_date=2013-06-04T18:32:12%2B00:00'
+```
+
+# Users
+
+### Get current user data
+```
+GET /me
+```
+
+### Get current user with related data
+```
+GET /me?with_related_data=true -Q
+```
+or
+```
+GET /me -q 'with_related_data=true'
+```
+
+### Sign up new user
+**Note:** This is not implemented in [togglv8](/) wrapper because it  will increase the cost of your Toggl account. See [Toggl Pricing and Payments](http://support.toggl.com/pricing-and-payments/) for details.
+```
+POST /signups -d '{"user":{"email":"<email_address>","password":"<password>"}}'
+```
+
+# Workspaces
+
+### Get user workspaces
+```
+GET /workspaces
+```
+
+### Get workspace users
+```
+GET /workspaces/282224/users
+```
+
+### Get workspace clients
+```
+GET /workspaces/282224/clients
+```
+
+### Get workspace projects
+```
+GET /workspaces/282224/projects
+```
+
+### Get workspace tasks
+```
+GET /workspaces/282224/tasks
+```
+```
+GET /workspaces/282224/tasks?active=true
+```
+```
+GET /workspaces/282224/tasks?active=false
+```
+```
+GET /workspaces/282224/tasks?active=both
+```
+
+# Workspace Users
+
+### Invite users to workspace
+**Note:** Not yet supported by [togglv8](/)
+
+### Update workspace user (can only update admin flag)
+**Note:** Call fails with error message "Cannot access workspace users"
+```
+PUT /workspace_users/282224 -d '{"workspace_user":{"admin":true}}'
+```
+
+### Delete workspace user
+**Note:** Not yet supported by [togglv8](/)
+
+### Get workspace users for a workspace
+**Note:** Not yet supported by [togglv8](/)

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in togglv8.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013-2015 Tom Kane
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,75 @@
+
+# Toggl API v8
+
+[![Build Status](https://api.travis-ci.org/kanet77/togglv8.svg "Build Status")](https://travis-ci.org/kanet77/togglv8) [![Coverage Status](https://coveralls.io/repos/kanet77/togglv8/badge.svg?branch=master&service=github)](https://coveralls.io/github/kanet77/togglv8?branch=master)
+
+[Toggl](http://www.toggl.com) is a time tracking tool.
+
+[togglv8](/) is a Ruby Wrapper for [Toggl API v8](https://github.com/toggl/toggl_api_docs). It is designed to mirror the Toggl API as closely as possible.
+
+**Note:** Currently togglv8 only includes calls to [Toggl API](https://github.com/toggl/toggl_api_docs/blob/master/toggl_api.md), not the [Reports API](https://github.com/toggl/toggl_api_docs/blob/master/reports.md)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'togglv8'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install togglv8
+
+## Usage
+
+This short example shows one way to create a time entry for the first workspace of the user identified by `<API_TOKEN>`:
+
+```ruby
+require 'togglv8'
+
+toggl_api    = TogglV8::API.new(<API_TOKEN>)
+user         = toggl_api.me(all=true)
+workspaces   = toggl_api.my_workspaces(user)
+workspace_id = workspaces.first['id']
+toggl_api.create_time_entry({description: "Workspace time entry",
+        wid: workspace_id,
+        duration: 1200,
+        start: "2015-08-18T01:13:40.000Z",
+        created_with: "My awesome Ruby application"})
+```
+
+See specs for more examples.
+
+## Documentation
+
+Run `rdoc` to generate documentation. Open `doc/index.html` in your browser.
+
+Also available on [DocumentUp](https://documentup.com/kanet77/togglv8)
+
+## Test Coverage
+
+Open `coverage/index.html` to see test coverage.
+
+As of 2015-08-21, coverage is "90.39% covered at 6.16 hits/line" according to [SimpleCov](https://rubygems.org/gems/simplecov).
+
+## Acknowledgements
+
+- Thanks to [Koen Van der Auwera](https://github.com/atog) for the [Ruby Wrapper for Toggl API v6](https://github.com/atog/toggl)
+- Thanks to the Toggl team for exposing the API.
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/togglv8/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+Copyright (c) 2013-2015 Tom Kane. Released under the [MIT License](http://opensource.org/licenses/mit-license.php). See [LICENSE.txt](LICENSE.txt) for details.

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require 'fileutils'
+
+task :clean do
+  FileUtils.remove_dir('coverage', force=true)
+  FileUtils.remove_dir('doc', force=true)
+  FileUtils.remove_dir('pkg', force=true)
+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/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