/togglex

Elixir Toggl API Wrapper

Primary LanguageElixir

Build Status Coverage Status Inline docs

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