toggl-client

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #llm #golang #docker #macos #windows #awesome #awesome-list #pytorch #ios #openai

(★ 19)

Client for the Toggl API built for async and await support

toggl-client Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Toggl-Client

Client for the Toggl API built for async and await support

## Usage

```bash
npm i toggl-client
```

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

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

## API

### Table of Contents

*   [TogglClient][1]
    *   [Properties][2]
*   [Workspaces][3]
    *   [list][4]
    *   [get][5]
        *   [Parameters][6]
    *   [update][7]
        *   [Parameters][8]
    *   [users][9]
        *   [Parameters][10]
    *   [clients][11]
        *   [Parameters][12]
    *   [groups][13]
        *   [Parameters][14]
    *   [projects][15]
        *   [Parameters][16]
    *   [tasks][17]
        *   [Parameters][18]
    *   [tags][19]
        *   [Parameters][20]
*   [Workspace][21]
    *   [Properties][22]
*   [defaultToEmpty][23]
    *   [Parameters][24]
*   [mapData][25]
    *   [Parameters][26]
*   [Clients][27]
    *   [list][28]
    *   [create][29]
        *   [Parameters][30]
    *   [get][31]
        *   [Parameters][32]
    *   [update][33]
        *   [Parameters][34]
    *   [delete][35]
        *   [Parameters][36]
    *   [projects][37]
        *   [Parameters][38]
*   [Groups][39]
    *   [create][40]
        *   [Parameters][41]
    *   [update][42]
        *   [Parameters][43]
    *   [delete][44]
        *   [Parameters][45]
*   [Tags][46]
    *   [validateTag][47]
        *   [Parameters][48]
    *   [create][49]
        *   [Parameters][50]
    *   [update][51]
        *   [Parameters][52]
    *   [delete][53]
        *   [Parameters][54]
*   [ProjectUsers][55]
    *   [get][56]
        *   [Parameters][57]
    *   [update][58]
        *   [Parameters][59]
    *   [delete][60]
        *   [Parameters][61]
    *   [create][62]
        *   [Parameters][63]
*   [Projects][64]
    *   [create][65]
        *   [Parameters][66]
    *   [get][67]
        *   [Parameters][68]
    *   [list][69]
        *   [Parameters][70]
    *   [update][71]
        *   [Parameters][72]
    *   [delete][73]
        *   [Parameters][74]
    *   [tasks][75]
        *   [Parameters][76]
*   [TimeEntries][77]
    *   [get][78]
        *   [Parameters][79]
    *   [delete][80]
        *   [Parameters][81]
    *   [list][82]
        *   [Parameters][83]
    *   [create][84]
        *   [Parameters][85]
    *   [start][86]
        *   [Parameters][87]
    *   [stop][88]
        *   [Parameters][89]
    *   [current][90]
    *   [update][91]
        *   [Parameters][92]
*   [Reports][93]
    *   [weekly][94]
        *   [Parameters][95]
    *   [weeklyAll][96]
        *   [Parameters][97]
    *   [details][98]
        *   [Parameters][99]
    *   [detailsAll][100]
        *   [Parameters][101]
    *   [summary][102]
        *   [Parameters][103]
    *   [summaryAll][104]
        *   [Parameters][105]
*   [User][106]
    *   [current][107]
    *   [update][108]
        *   [Parameters][109]
    *   [resetToken][110]

## TogglClient

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

### Properties

*   `workspaces` **[Workspaces][3]**&#x20;
*   `projects` **[Projects][15]**&#x20;
*   `timeEntries` **[TimeEntries][77]**&#x20;
*   `clients` **[Clients][11]**&#x20;
*   `groups` **[Groups][13]**&#x20;
*   `tags` **[Tags][19]**&#x20;
*   `projectUsers` **[ProjectUsers][55]**&#x20;
*   `user` **[User][106]**&#x20;

## Workspaces

Access workspaces. See [https://github.com/toggl/toggl\_api\_docs/blob/master/chapters/workspaces.md][111]

### list

Lists all workspaces

Returns **[Array][112]<[Workspace][21]>** List of workspaces

### get

Gets a workspace by id

#### Parameters

*   `id` **([number][113] | [string][114])** if of the workspace

Returns **([Workspace][21] | [undefined][115])** Workspace or undefined if the given workspace does not exist

### update

Updates an existing workspace

#### Parameters

*   `id` **([number][113] | [string][114])** Id of the workspace to be updated
*   `workspace` **[Workspace][21]**&#x20;

Returns **[Workspace][21]** The updated workspace

### users

Gets a list of users associated with the workspace

#### Parameters

*   `id` **([number][113] | [string][114])** 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][113] | [string][114])** 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][113] | [string][114])** 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][113] | [string][114])** 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][113] | [string][114])** 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][113] | [string][114])** Id of the workspace

Returns **any** List of tags associated with the workspace

## Workspace

Type: [Object][116]

### Properties

*   `id` **[number][113]** Id of the workspace
*   `name` **[number][113]** Name of the workspace
*   `premium` **[boolean][117]** True if premium features are enabled
*   `admin` **[boolean][117]** True if requesting user has admin access to the workspace
*   `default_hourly_rate` **[number][113]** Default hourly rate only shown for requesting admin users
*   `default_currency` **[string][114]** Default currency
*   `only_admins_may_create_projects` **[boolean][117]**&#x20;
*   `only_admins_see_billable_rates` **[boolean][117]**&#x20;
*   `only_admins_see_team_dashboard` **[boolean][117]**&#x20;
*   `rounding` **[number][113]** type of rounding
*   `rounding_minutes` **[number][113]** round up to nearest minute
*   `at` **[date][118]** 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][119]

### list

Gets a list of clients

Returns **any** an array of clients

### create

Creates a new client

#### Parameters

*   `client` **any**&#x20;

Returns **any** Created client

### get

Gets a client by id

#### Parameters

*   `id` **([number][113] | [string][114])**&#x20;

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

### update

Updates a client

#### Parameters

*   `id` **([number][113] | [string][114])**&#x20;
*   `client` &#x20;

Returns **any** updated client

### delete

Deletes a client by id

#### Parameters

*   `id` **([number][113] | [string][114])**&#x20;

### projects

Lists projects associated with the given client

#### Parameters

*   `id` **([number][113] | [string][114])**&#x20;
*   `active` &#x20;
*   `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][120]

### create

Creates a group

#### Parameters

*   `group` **any**&#x20;

Returns **any** group created

### update

Updates a group

#### Parameters

*   `id` **([number][113] | [string][114])** group id that should be updated
*   `group` **any**&#x20;

Returns **any** result of update operation

### delete

Deletes a group

#### Parameters

*   `id` **([number][113] | [string][114])** group id that should be deleted

## Tags

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

### validateTag

Validates that a tag contains the name property.

#### Parameters

*   `tag` **[Object][116]** The tag object to be validated

*   Throws **[Error][122]** 'The tag must include name'

### create

Creates a new tag

#### Parameters

*   `workspace_id` **[number][113]** Id of the workspace
*   `tag` **[object][116]** A tag object with the property `name` and optionally `workspace_id`

Returns **any** Tag created

### update

Updates an existing tag

#### Parameters

*   `workspace_id` **[number][113]** Id of the workspace
*   `id` **([number][113] | [string][114])** Id of the tag to be updated
*   `tag` **[object][116]** A tag object with the property `name` and optionally `workspace_id`

Returns **any** Updated tag

### delete

Deletes an existing tag

#### Parameters

*   `workspace_id` **[number][113]** Id of the workspace
*   `id` **([number][113] | [string][114])** 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][123]

### get

Gets a project user by id

#### Parameters

*   `id` **([number][113] | [string][114])**&#x20;

### update

Updates an existing project user

#### Parameters

*   `id` **([number][113] | [string][114])** Id of the project user to update
*   `project_user` **any**&#x20;

### delete

Deletes an existing project user

#### Parameters

*   `id` **([number][113] | [string][114])**&#x20;

### create

Creates a new project user

#### Parameters

*   `project_user` **any**&#x20;

Returns **any** project user created

## Projects

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

### create

Creates a new project

#### Parameters

*   `workspace_id` **([number][113])** Id of the workspace to be updated
*   `project` **any**&#x20;

Returns **any** Project created

### get

Gets an existing project by id

#### Parameters

*   `workspace_id` **([number][113])** Id of the project to get
*   `project_id` **([number][113])** 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][113])** Id of the project to get
*   `project_id` **([number][113])** 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][113])** Id of the workspace to be updated
*   `project_id` **([number][113])** Id of the project to be updated
*   `project` **any**&#x20;

Returns **any** The updated project

### delete

Deletes an existing project

#### Parameters

*   `workspace_id` &#x20;
*   `project_id` &#x20;
*   `id` **([number][113])** Id of the project to be deleted

### tasks

Gets tasks associated with the given project

#### Parameters

*   `workspace_id` &#x20;
*   `project_id` &#x20;
*   `id` **([number][113])** 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][125]

### 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**&#x20;

Returns **any** TimeEntry

### delete

Delete an existing time entry

#### Parameters

*   `id` **[number][113]**&#x20;

### 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**&#x20;

### start

Creates a new time entry

#### Parameters

*   `time_entry` **any** must include `workspace_id` and `start`

Returns **any**&#x20;

### stop

Stops the current running time entry

#### Parameters

*   `time_entry` &#x20;

Returns **any**&#x20;

### current

Gets the current running time entry

Returns **any**&#x20;

### update

Updates an existing time entry

#### Parameters

*   `id` **[number][113]**&#x20;
*   `time_entry` **any**&#x20;

Returns **any**&#x20;

## Reports

Access reports. See [https://github.com/toggl/toggl\_api\_docs/blob/master/reports.md][126]

### weekly

Weekly report
[https://developers.track.toggl.com/docs/reports/weekly\_reports#post-search-time-entries][127]

#### Parameters