Toggl API for Node.js

1.0.2 verified Sat Apr 25 auth: no javascript

A Node.js client library for interacting with the Toggl time tracking API. Currently at version 1.0.2, this package provides a simple wrapper around Toggl's REST API endpoints, supporting authentication via API tokens and enabling operations such as fetching time entries, projects, and workspaces. It is a lightweight, dependency-light solution for integrating Toggl into Node.js applications, though it lacks TypeScript definitions and has limited documentation. The library follows a callback-based pattern typical of older Node.js packages.

Common errors

error TypeError: toggl.getTimeEntries is not a function ↓

cause Incorrectly importing the module; e.g., using default import without new keyword.

fix

Ensure you do: const TogglClient = require('toggl-api'); const toggl = new TogglClient(token);

error Error: Invalid API token ↓

cause Passing an invalid or expired API token to constructor.

fix

Verify your Toggl API token from Toggl settings and ensure it is active.

error RequestError: getaddrinfo ENOTFOUND api.track.toggl.com ↓

cause Network DNS resolution failure, possibly due to no internet or proxy issues.

fix

Check your network connection and DNS settings. Ensure api.track.toggl.com is reachable.

Warnings

gotcha Constructor expects API token as first argument; passing anything else will cause authentication failures. ↓

fix Ensure you pass a valid Toggl API token string (not email/password) to the constructor.

gotcha Package uses callbacks and does not support Promises natively. No promise wrappers provided. ↓

fix Use util.promisify() to convert callback methods to Promise-based usage.

gotcha No TypeScript definitions available. Using in a TypeScript project will require manual type declarations. ↓

fix Create a .d.ts file or use a type assertion (any) for the client instance.

gotcha Package has limited error handling; network errors may not provide detailed messages. ↓

fix Implement custom error handling and check err object for status codes.

deprecated Toggl API v8 endpoints (used by this library) are deprecated; Toggl has moved to v9. ↓

fix Consider migrating to a library supporting Toggl API v9 or directly calling the new API.

Install

npm install toggl-api

yarn add toggl-api

pnpm add toggl-api

Imports

TogglClient
wrong
```
import TogglClient from 'toggl-api';
```
correct
```
const TogglClient = require('toggl-api');
```
This package is CommonJS only; ESM import does not work out of the box.
TogglClient
```
import TogglClient from 'toggl-api';
```
If using a bundler or Node.js with esm, you may need to use default interop. However, the package has no default export; use require or wrap.
toggl
wrong
```
const toggl = require('toggl-api')('api_token');
```
correct
```
const toggl = new (require('toggl-api'))('api_token');
```
The module exports the constructor, not an instance. You must call new on the required value.

Quickstart

Demonstrates creating a Toggl client with an API token, fetching time entries, and listing workspaces using callbacks.

const TogglClient = require('toggl-api');
const toggl = new TogglClient(process.env.TOGGL_API_TOKEN ?? '');

toggl.getTimeEntries({ start_date: '2023-01-01', end_date: '2023-01-31' }, (err, entries) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(entries);
});

toggl.getWorkspaces((err, workspaces) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(workspaces);
});