Toggl-Client

Client for the Toggl API built for async and await support

Usage

npm i toggl-client

const togglClient = require('toggl-client');

const client = togglClient({ apiToken: YOUR_API_TOKEN });

API

Table of Contents

• TogglClient
  • Properties
• Workspaces
  • list
  • get
    • Parameters
  • update
    • Parameters
  • users
    • Parameters
  • clients
    • Parameters
  • groups
    • Parameters
  • projects
    • Parameters
  • tasks
    • Parameters
  • tags
    • Parameters
• Workspace
  • Properties
• defaultToEmpty
  • Parameters
• mapData
  • Parameters
• Clients
  • list
  • create
    • Parameters
  • get
    • Parameters
  • update
    • Parameters
  • delete
    • Parameters
  • projects
    • Parameters
• Groups
  • create
    • Parameters
  • update
    • Parameters
  • delete
    • Parameters
• Tags
  • validateTag
    • Parameters
  • create
    • Parameters
  • update
    • Parameters
  • delete
    • Parameters
• ProjectUsers
  • get
    • Parameters
  • update
    • Parameters
  • delete
    • Parameters
  • create
    • Parameters
• Projects
  • create
    • Parameters
  • get
    • Parameters
  • list
    • Parameters
  • update
    • Parameters
  • delete
    • Parameters
  • tasks
    • Parameters
• TimeEntries
  • get
    • Parameters
  • delete
    • Parameters
  • list
    • Parameters
  • create
    • Parameters
  • start
    • Parameters
  • stop
    • Parameters
  • current
  • update
    • Parameters
• Reports
  • weekly
    • Parameters
  • weeklyAll
    • Parameters
  • details
    • Parameters
  • detailsAll
    • Parameters
  • summary
    • Parameters
  • summaryAll
    • Parameters
• User
  • current
  • update
    • Parameters
  • resetToken

TogglClient

Main class to interact with the toggl API. Calling togglClient({ apiToken: YOUR_API_TOKEN }); returns an instance of this class.

Properties

• workspaces Workspaces
• projects Projects
• timeEntries TimeEntries
• clients Clients
• groups Groups
• tags Tags
• projectUsers ProjectUsers
• user User

Workspaces

Access workspaces. See https://github.com/toggl/toggl_api_docs/blob/master/chapters/workspaces.md

list

Lists all workspaces

Returns Array<Workspace> List of workspaces

get

Gets a workspace by id

Parameters

• id (number | string) if of the workspace

Returns (Workspace | undefined) Workspace or undefined if the given workspace does not exist

update

Updates an existing workspace

Parameters

• id (number | string) Id of the workspace to be updated
• workspace Workspace

Returns Workspace The updated workspace

users

Gets a list of users associated with the workspace

Parameters

• id (number | string) Id of the workspace

Returns any List of users associated with the workspace

clients

Gets a list of clients associated with the workspace

Parameters

• id (number | string) Id of the workspace

Returns any List of clients associated with the workspace

groups

Gets a list of groups associated with the workspace

Parameters

• id (number | string) Id of the workspace

Returns any List of groups associated with the workspace

projects

Gets a list of projects associated with the workspace

Parameters

• id (number | string) Id of the workspace

Returns any List of projects associated with the workspace

tasks

Gets a list of tasks associated with the workspace

Parameters

• id (number | string) Id of the workspace

Returns any List of tasks associated with the workspace

tags

Gets a list of tags associated with the workspace

Parameters

• id (number | string) Id of the workspace

Returns any List of tags associated with the workspace

Workspace

Type: Object

Properties

• id number Id of the workspace
• name number Name of the workspace
• premium boolean True if premium features are enabled
• admin boolean True if requesting user has admin access to the workspace
• default_hourly_rate number Default hourly rate only shown for requesting admin users
• default_currency string Default currency
• only_admins_may_create_projects boolean
• only_admins_see_billable_rates boolean
• only_admins_see_team_dashboard boolean
• rounding number type of rounding
• rounding_minutes number round up to nearest minute
• at date Indicates when the workspace was created or updated

defaultToEmpty

Returns the input data or an empty array

Parameters

• data any Input data

Returns any any

mapData

Parses the input and returns the data property or an undefined This was used heavily in the v8 API and may no longer be needed in v9.

Parameters

• res any A response from the Toggl API

Returns any object||undefined

Clients

Access clients. See https://github.com/toggl/toggl_api_docs/blob/master/chapters/clients.md

list

Gets a list of clients

Returns any an array of clients

create

Creates a new client

Parameters

• client any

Returns any Created client

get

Gets a client by id

Parameters

• id (number | string)

Returns any client or undefined if no client with specified id was found

update

Updates a client

Parameters

• id (number | string)
• client

Returns any updated client

delete

Deletes a client by id

Parameters

• id (number | string)

projects

Lists projects associated with the given client

Parameters

• id (number | string)
• active
• String active filter active clients by specifying true/false/both

Groups

Access groups. See https://github.com/toggl/toggl_api_docs/blob/master/chapters/groups.md

create

Creates a group

Parameters

• group any

Returns any group created

update

Updates a group

Parameters

• id (number | string) group id that should be updated
• group any

Returns any result of update operation

delete

Deletes a group

Parameters

• id (number | string) group id that should be deleted

Tags

Access Tags. See https://developers.track.toggl.com/docs/api/tags

validateTag

Validates that a tag contains the name property.

Parameters

• tag Object The tag object to be validated

• Throws Error 'The tag must include name'

create

Creates a new tag

Parameters

• workspace_id number Id of the workspace
• tag object A tag object with the property name and optionally workspace_id

Returns any Tag created

update

Updates an existing tag

Parameters

• workspace_id number Id of the workspace
• id (number | string) Id of the tag to be updated
• tag object A tag object with the property name and optionally workspace_id

Returns any Updated tag

delete

Deletes an existing tag

Parameters

• workspace_id number Id of the workspace
• id (number | string) If of the tag to be deleted

ProjectUsers

Access project users. See https://github.com/toggl/toggl_api_docs/blob/master/chapters/project_users.md

get

Gets a project user by id

Parameters

• id (number | string)

update

Updates an existing project user

Parameters

• id (number | string) Id of the project user to update
• project_user any

delete

Deletes an existing project user

Parameters

• id (number | string)

create

Creates a new project user

Parameters

• project_user any

Returns any project user created

Projects

Access projects. See https://developers.track.toggl.com/docs/api/projects

create

Creates a new project

Parameters

• workspace_id (number) Id of the workspace to be updated
• project any

Returns any Project created

get

Gets an existing project by id

Parameters

• workspace_id (number) Id of the project to get
• project_id (number) Id of the project to get

Returns any Project if a project with the specified id exists, othererwise undefined

list

Gets all projects

Parameters

• workspace_id (number) Id of the project to get
• project_id (number) Id of the project to get

Returns any Project if a project with the specified id exists, othererwise undefined

update

Updates an existing project

Parameters

• workspace_id (number) Id of the workspace to be updated
• project_id (number) Id of the project to be updated
• project any

Returns any The updated project

delete

Deletes an existing project

Parameters

• workspace_id
• project_id
• id (number) Id of the project to be deleted

tasks

Gets tasks associated with the given project

Parameters

• workspace_id
• project_id
• id (number) Id of the project

Returns any Array of tasks associated with the project

TimeEntries

Access time entries. See https://github.com/toggl/toggl_api_docs/blob/master/chapters/time_entries.md

get

Gets the time entry specified by id. Due to limitations of the v9 API, start_date must not be earlier than 3 months ago. If you want results further back, use the reports endpoints.

Parameters

• id any

Returns any TimeEntry

delete

Delete an existing time entry

Parameters

• id number

list

Lists time entries. The query must include start_date and end_date. Note that due to limitations of the v9 API, start_date must not be earlier 3 months ago. If you want results further back, use the reports endpoints.

Parameters

• query any must include start_date and end_date and must be within the last 30 days.

Returns any List of time entries

create

Creates a new time entry

Parameters

• time_entry any must include workspace_id and start

Returns any

start

Creates a new time entry

Parameters

• time_entry any must include workspace_id and start

Returns any

stop

Stops the current running time entry

Parameters

• time_entry

Returns any

current

Gets the current running time entry

Returns any

update

Updates an existing time entry

Parameters

• id number
• time_entry any

Returns any

Reports

Access reports. See https://github.com/toggl/toggl_api_docs/blob/master/reports.md

weekly

Weekly report https://developers.track.toggl.com/docs/reports/weekly_reports#post-search-time-entries

Parameters

• workspaceId
• params

weeklyAll

Weekly report containing all pages fetched with wait time between requests of 1010ms https://developers.track.toggl.com/docs/reports/weekly_reports#post-search-time-entries

Parameters

• workspaceId
• params

details

Detailed report URL: GET https://api.track.toggl.com/reports/api/v3/workspace/{workspace_id}/search/time_entries https://developers.track.toggl.com/docs/reports/detailed_reports#post-load-totals-detailed-report params must include start_date

Parameters

• workspaceId
• params

detailsAll

Detailed report containing all pages fetched with wait time between requests of 1010ms URL: GET https://api.track.toggl.com/reports/api/v3/workspace/{workspace_id}/search/time_entries https://developers.track.toggl.com/docs/reports/detailed_reports#post-load-totals-detailed-report params must include start_date

Parameters

• workspaceId
• params

summary

Summary report URL: GET https://api.track.toggl.com/reports/api/v2/summary

Parameters

• workspaceId
• params

summaryAll

Summary report containing all pages fetched with wait time between requests of 1010ms URL: GET https://api.track.toggl.com/reports/api/v2/summary

Parameters

• workspaceId
• params

User

Access users. See https://developers.track.toggl.com/docs/api/me

current

Gets the current user

Returns any The current user.See https://developers.track.toggl.com/docs/api/me#get-me

update

Updates the user. You can only update country_id, current_password, default_workspace_id, email, fullname,name, password, timezone

See https://developers.track.toggl.com/docs/api/me#put-me

Parameters

• user any

Returns any The updated user.

resetToken

Resets API token https://developers.track.toggl.com/docs/api/authentication#post-resettoken

Returns any New API token {String}