Awesome
Togglex
Simple Elixir wrapper for the Toggl API.
Heavily based on ExTracker and Tentacat.
Installation
The package can be installed as:
- Add togglex to your list of dependencies in
mix.exs
:
def deps do
[{:togglex, "~> 0.1.0"}]
end
- Ensure togglex is started before your application:
def application do
[applications: [:togglex]]
end
Usage
All calls to Toggl APIs must use a Client which contains the access token and the endpoint. The API is splitted in two different parts. The first one is called Toggl API which is essentially a RESTful API that you can use to create, update, delete and get most of the resources from Toggl service. On the other hand there is a read-only Reports API which you can use to obtain aggregated data based on more or less complex queries.
Toggl API examples
Initializing the client for the Toggl API endpoint:
client = Togglex.Client.new(%{access_token: "YOU_ACCESS_TOKEN"}, :api)
Get workspace projects:
Togglex.Api.Workspaces.projects(client, "YOUR_WORKSPACE_ID")
Reports API examples
Initializing the client for the Reports API endpoint:
client = Togglex.Client.new(%{access_token: "YOU_ACCESS_TOKEN"}, :reports)
Getting a detailed report based on some parameters:
Togglex.Reports.detailed(client, %{workspace_id: "YOUR_WORKSPACE_ID", project_ids: "COMMA_SEPARATED_PROJECT_IDS"})
Getting a summarized report based on some parameters:
Togglex.Reports.summary(client, %{workspace_id: "YOUR_WORKSPACE_ID", project_ids: "COMMA_SEPARATED_PROJECT_IDS"})
PDF Reports
Toggl allows you to retrieve reports in PDF format. To do that you only need to
call a report function passing :pdf
atom as last parameter. The value returned
is a binary you can use to write a file:
pdf = Togglex.Reports.summary(client, %{workspace_id: "YOUR_WORKSPACE_ID", project_ids: "COMMA_SEPARATED_PROJECT_IDS"}, :pdf)
File.write!(path, pdf)
Check out in the next section which API calls are already implemented in this wrapper.
Features
Toggl API
-
Authenticate and get user data
- HTTP Basic Auth with e-mail and password
- HTTP Basic Auth with API token
- Authentication with a session cookie
- Destroy the session
-
Clients
- create a client
- get client details
- update a client
- delete a client
- get clients visible to user
- get client projects
-
Projects
- create a project
- get project data
- update project data
- delete a project
- get project users
- get project tasks
- delete multiple projects
-
Project users
- create a project user
- update a project user
- delete a project user
- add multiple users to a project
- update multiple project users
- delete multiple project users
-
Tags
- create a tag
- update a tag
- delete a tag
-
Tasks (available only for pro workspaces)
- create a task
- get task details
- update a task
- delete a task
- update multiple tasks
- delete multiple tasks
-
Time entries
- create a time entry
- start a time entry
- stop a time entry
- get time entry details
- get running time entry
- update time entry
- delete time entry
- get time entries started in a specific time range
- bulk update time entries tags
-
Users
- get current user data and time entries
- update current user data
- reset API token
- sign up new user
-
Workspaces
- get user workspaces
- get single workspace
- get workspace users
- get workspace clients
- get workspace projects
- get workspace tasks
- get workspace tags
- update workspace
-
Workspace users
- invite users to workspace
- update workspace user
- delete workspace user
- get workspace users for a workspace
-
Dashboard
- get a generic overview of your team
Reports API
- Weekly report
- Detailed report
- Summary report
- Project dashboard