/toggl_rb

Toggl V9 API Client

Primary LanguageRubyMIT LicenseMIT

TogglRb

Ruby Coverage Status Gem Version

A ruby API client for toggl's V9 API and V3 Reports API.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add toggl_rb

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install toggl_rb

Usage

Authentication

To use the Toggl API you need an API token, this can be found on the profile settings page.

You can then setup the token for all instances of TogglRb's connections to the API:

# Assuming API token is stored in an environmental variable, this will setup an API token for all TogglRb connections
TogglRb.config.api_token = ENV.fetch("TOGGL_API_TOKEN", "")

# Alternatively, if you need more granular control you can set up a connection and endpoints with a token:
core_connection = TogglRb::Connection.core_connection
core_connection.api_token = ENV.fetch("TOGGL_API_TOKEN_TWO", "")
projects_endpoint = TogglRb::Core::Projects.new(core_connection)
# projects_endpoint requests will use TOGGL_API_TOKEN_TWO rather than TOGGL_API_TOKEN setup globally

Endpoints

Currently TogglRb only supports a select subset of endpoints:

Group Endpoint Status
Me GET Me ✔️
Me PUT Me ✔️
Me GET Clients 🔲
Me GET Features 🔲
Me GET User's last known location 🔲
Me GET Logged 🔲
Me GET Organizations that a user is part of 🔲
Me GET Projects 🔲
Me GET ProjectsPaginated 🔲
Me GET Tags 🔲
Me GET Tasks 🔲
Me GET TrackReminders 🔲
Me GET WebTimer 🔲
Me GET Workspaces 🔲
Groups GET List of groups in a workspace within an organization with user assignments ✔️
ProjectUsers GET Get workspace projects users 🔲
ProjectUsers POST Add an user into workspace projects users 🔲
ProjectUsers PATCH Patch project users from workspace 🔲
ProjectUsers PUT Update an user into workspace projects users 🔲
ProjectUsers DELETE Delete a project user from workspace projects users 🔲
Projects GET WorkspaceProjects 🔲
Projects PATCH WorkspaceProjects ✔️
Projects POST WorkspaceProjects ✔️
Projects GET WorkspaceProject ✔️
Projects PUT WorkspaceProject ✔️
Projects DELETE WorkspaceProject ✔️
Users GET List of users who belong to the given workspace ✔️
TimeEntries GET TimeEntries ✔️
TimeEntries GET Get current time entry ✔️
TimeEntries GET Get a time entry by ID ✔️
TimeEntries POST TimeEntries ✔️
TimeEntries PATCH Bulk editing time entries ✔️
TimeEntries PUT TimeEntries ✔️
TimeEntries DELETE TimeEntries ✔️
TimeEntries PATCH Stop TimeEntry ✔️
Workspaces POST Create a new workspace 🔲
Workspaces GET List of users who belong to the given workspace 🔲
Workspaces PATCH Changes the users in a workspace 🔲
Workspaces POST Workspaces 🔲
Workspaces GET Get single workspace ✔️
Workspaces PUT Update workspace 🔲
Workspaces POST Alerts 🔲
Workspaces DELETE Alerts 🔲
Workspaces GET Workspace statistics 🔲
Workspaces GET Get workspace time entry constraints 🔲
Workspaces GET TrackReminders 🔲
Workspaces POST TrackReminders 🔲
Workspaces PUT TrackReminder 🔲
Workspaces DELETE TrackReminder 🔲
Workspaces GET Get workspace users 🔲
Workspaces PUT Update workspace user 🔲
Workspaces POST Change a lost password 🔲
Workspaces DELETE Delete workspace user 🔲

On The Reporting Endpoints

Group Endpoint Status
Detailed POST Search time entries ✔️
Detailed POST Export detailed report 🔲
Detailed POST Export detailed report 🔲
Detailed POST Load totals detailed report 🔲
Summary POST List project users 🔲
Summary POST Load project summary 🔲
Summary POST Search time entries ✔️
Summary POST Export summary report 🔲
Summary POST Export summary report 🔲

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/mcordell/toggl_rb.