TogglRb

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.