Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/saintedlama/toggl-client
Client for the Toggl API built for async and await support
https://github.com/saintedlama/toggl-client
api-client toggl
Last synced: 16 days ago
JSON representation
Client for the Toggl API built for async and await support
- Host: GitHub
- URL: https://github.com/saintedlama/toggl-client
- Owner: saintedlama
- License: isc
- Created: 2019-10-05T13:07:45.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-06-14T00:45:58.000Z (5 months ago)
- Last Synced: 2024-06-19T04:24:54.687Z (5 months ago)
- Topics: api-client, toggl
- Language: JavaScript
- Size: 473 KB
- Stars: 13
- Watchers: 3
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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]**
* `projects` **[Projects][15]**
* `timeEntries` **[TimeEntries][77]**
* `clients` **[Clients][11]**
* `groups` **[Groups][13]**
* `tags` **[Tags][19]**
* `projectUsers` **[ProjectUsers][55]**
* `user` **[User][106]**
## 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]**
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]**
* `only_admins_see_billable_rates` **[boolean][117]**
* `only_admins_see_team_dashboard` **[boolean][117]**
* `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**
Returns **any** Created client
### get
Gets a client by id
#### Parameters
* `id` **([number][113] | [string][114])**
Returns **any** client or undefined if no client with specified id was found
### update
Updates a client
#### Parameters
* `id` **([number][113] | [string][114])**
* `client`
Returns **any** updated client
### delete
Deletes a client by id
#### Parameters
* `id` **([number][113] | [string][114])**
### projects
Lists projects associated with the given client
#### Parameters
* `id` **([number][113] | [string][114])**
* `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][120]
### create
Creates a group
#### Parameters
* `group` **any**
Returns **any** group created
### update
Updates a group
#### Parameters
* `id` **([number][113] | [string][114])** group id that should be updated
* `group` **any**
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])**
### update
Updates an existing project user
#### Parameters
* `id` **([number][113] | [string][114])** Id of the project user to update
* `project_user` **any**
### delete
Deletes an existing project user
#### Parameters
* `id` **([number][113] | [string][114])**
### 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][124]
### create
Creates a new project
#### Parameters
* `workspace_id` **([number][113])** Id of the workspace to be updated
* `project` **any**
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**
Returns **any** The updated project
### delete
Deletes an existing project
#### Parameters
* `workspace_id`
* `project_id`
* `id` **([number][113])** Id of the project to be deleted
### tasks
Gets tasks associated with the given project
#### Parameters
* `workspace_id`
* `project_id`
* `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**
Returns **any** TimeEntry
### delete
Delete an existing time entry
#### Parameters
* `id` **[number][113]**
### 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][113]**
* `time_entry` **any**
Returns **any**
## 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
* `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][127]
#### Parameters
* `workspaceId`
* `params`
### details
Detailed report URL: GET [https://api.track.toggl.com/reports/api/v3/workspace/{workspace\_id}/search/time\_entries][128]
[https://developers.track.toggl.com/docs/reports/detailed\_reports#post-load-totals-detailed-report][129]
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][128]
[https://developers.track.toggl.com/docs/reports/detailed\_reports#post-load-totals-detailed-report][129]
params must include start\_date
#### Parameters
* `workspaceId`
* `params`
### summary
Summary report URL: GET [https://api.track.toggl.com/reports/api/v2/summary][130]
#### 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][130]
#### Parameters
* `workspaceId`
* `params`
## User
Access users. See [https://developers.track.toggl.com/docs/api/me][131]
### current
Gets the current user
Returns **any** The current user.See [https://developers.track.toggl.com/docs/api/me#get-me][132]
### 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][133]
#### Parameters
* `user` **any**
Returns **any** The updated user.
### resetToken
Resets API token [https://developers.track.toggl.com/docs/api/authentication#post-resettoken][134]
Returns **any** New API token {String}
[1]: #togglclient
[2]: #properties
[3]: #workspaces
[4]: #list
[5]: #get
[6]: #parameters
[7]: #update
[8]: #parameters-1
[9]: #users
[10]: #parameters-2
[11]: #clients
[12]: #parameters-3
[13]: #groups
[14]: #parameters-4
[15]: #projects
[16]: #parameters-5
[17]: #tasks
[18]: #parameters-6
[19]: #tags
[20]: #parameters-7
[21]: #workspace
[22]: #properties-1
[23]: #defaulttoempty
[24]: #parameters-8
[25]: #mapdata
[26]: #parameters-9
[27]: #clients-1
[28]: #list-1
[29]: #create
[30]: #parameters-10
[31]: #get-1
[32]: #parameters-11
[33]: #update-1
[34]: #parameters-12
[35]: #delete
[36]: #parameters-13
[37]: #projects-1
[38]: #parameters-14
[39]: #groups-1
[40]: #create-1
[41]: #parameters-15
[42]: #update-2
[43]: #parameters-16
[44]: #delete-1
[45]: #parameters-17
[46]: #tags-1
[47]: #validatetag
[48]: #parameters-18
[49]: #create-2
[50]: #parameters-19
[51]: #update-3
[52]: #parameters-20
[53]: #delete-2
[54]: #parameters-21
[55]: #projectusers
[56]: #get-2
[57]: #parameters-22
[58]: #update-4
[59]: #parameters-23
[60]: #delete-3
[61]: #parameters-24
[62]: #create-3
[63]: #parameters-25
[64]: #projects-2
[65]: #create-4
[66]: #parameters-26
[67]: #get-3
[68]: #parameters-27
[69]: #list-2
[70]: #parameters-28
[71]: #update-5
[72]: #parameters-29
[73]: #delete-4
[74]: #parameters-30
[75]: #tasks-1
[76]: #parameters-31
[77]: #timeentries
[78]: #get-4
[79]: #parameters-32
[80]: #delete-5
[81]: #parameters-33
[82]: #list-3
[83]: #parameters-34
[84]: #create-5
[85]: #parameters-35
[86]: #start
[87]: #parameters-36
[88]: #stop
[89]: #parameters-37
[90]: #current
[91]: #update-6
[92]: #parameters-38
[93]: #reports
[94]: #weekly
[95]: #parameters-39
[96]: #weeklyall
[97]: #parameters-40
[98]: #details
[99]: #parameters-41
[100]: #detailsall
[101]: #parameters-42
[102]: #summary
[103]: #parameters-43
[104]: #summaryall
[105]: #parameters-44
[106]: #user
[107]: #current-1
[108]: #update-7
[109]: #parameters-45
[110]: #resettoken
[111]: https://github.com/toggl/toggl_api_docs/blob/master/chapters/workspaces.md
[112]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
[113]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
[114]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[115]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
[116]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[117]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
[118]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date
[119]: https://github.com/toggl/toggl_api_docs/blob/master/chapters/clients.md
[120]: https://github.com/toggl/toggl_api_docs/blob/master/chapters/groups.md
[121]: https://developers.track.toggl.com/docs/api/tags
[122]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error
[123]: https://github.com/toggl/toggl_api_docs/blob/master/chapters/project_users.md
[124]: https://developers.track.toggl.com/docs/api/projects
[125]: https://github.com/toggl/toggl_api_docs/blob/master/chapters/time_entries.md
[126]: https://github.com/toggl/toggl_api_docs/blob/master/reports.md
[127]: https://developers.track.toggl.com/docs/reports/weekly_reports#post-search-time-entries
[128]: https://api.track.toggl.com/reports/api/v3/workspace/{workspace_id}/search/time_entries
[129]: https://developers.track.toggl.com/docs/reports/detailed_reports#post-load-totals-detailed-report
[130]: https://api.track.toggl.com/reports/api/v2/summary
[131]: https://developers.track.toggl.com/docs/api/me
[132]: https://developers.track.toggl.com/docs/api/me#get-me
[133]: https://developers.track.toggl.com/docs/api/me#put-me
[134]: https://developers.track.toggl.com/docs/api/authentication#post-resettoken