diacode / togglex

Elixir Toggl API Wrapper

Togglex

Simple Elixir wrapper for the Toggl API.

Heavily based on ExTracker and Tentacat.

Installation

The package can be installed as:

1. Add togglex to your list of dependencies in mix.exs:

def deps do
  [{:togglex, "~> 0.1.0"}]
end

2. 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