npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

grunt-toggl

v1.0.0

Published

Toggl API for Grunt. E.g. start time tracking with `grunt watch` or `grunt toggl`

Downloads

23

Readme

grunt-toggl

Toggl API for Grunt. E.g. start time tracking with grunt watch or grunt toggl

Upstream Build Status: Linux dependencies NPM version npm Badge

Demo

Demo of starting a timer from the command line

Getting Started

This plugin requires Grunt >=0.4.4

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-toggl --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-toggl');

The "toggl" task

Overview

In your project's Gruntfile, add a section named toggl to the data object passed into grunt.initConfig().

grunt.initConfig({
  toggl: {
    options: {
      apiKey: '',
      settingsFile: 'toggl.json'
      workspace:    null,
      project:      null,
      data: {
        description: '<%= pkg.name %>',
      }
    }
  },
});

Options

Your Toggl API key is required for this task. Get it from your profile on Toggl.com https://www.toggl.com/app/#profile.

Here are the ways to specify your API key:

options.apiKey

Type: String Default value: ``

This is one way to specify your Toggl API key. Not secure if your repo is public.

options.apiEnvVar

Type: String Default value: ``

This is one way to specify your Toggl API key. Safe but you'll have to configure the shell env var on the machine you're using the task on.

options.settingsFile

Type: String Default value: .toggl

This is another way to specify your Toggl API Key. Enter a filename to a JSON file that contains the key "apiKey" and value with your Toggl API key.

{
  "apiKey":     "demokeydemokeydemokey",
  "workspace":  12345
  "project":    1111111
}

You can also specify the workspace here.

This format is useful if you keep your Gruntfile in version control and don't want your API key in it (e.g. add your .toggl file to your .gitignore).

Other options

options.workspace

Type: Integer Default value: null

OPTIONAL (if specified in settingsFile). Equivalent to options.data.wid. Specify the Toggl Workspace ID that newly created time entries should go into.

options.project

Type: Integer Default value: null

OPTIONAL. Equivalent to options.data.pid. Specify the Toggl Project ID that newly created time entries should go into.

options.data

Type: Object Default value: {}

The data object can take any values from the toggl time_entries API endpoint:

  • description: (string, strongly suggested to be used)

    • I like to use the package.json name in the description, assuming you have it loaded into the pkg variable (pkg: grunt.file.readJSON('package.json')):

      data: {
        description: '<%= pkg.name %>'
      }
  • wid: workspace ID (integer, required if pid or tid not supplied).

  • pid: project ID (integer, not required)

  • tid: task ID (integer, not required)

  • billable: (boolean, not required, default false, available for pro workspaces)

  • start: time entry start time (string, required, ISO 8601 date and time)

  • stop: time entry stop time (string, not required, ISO 8601 date and time)

  • duration: time entry duration in seconds. If the time entry is currently running, the duration attribute contains a negative value, denoting the start of the time entry in seconds since epoch (Jan 1 1970). The correct duration can be calculated as current_time + duration, where current_time is the current time in seconds since epoch. (integer, required)

  • created_with: the name of your client app (string, required)

  • tags: a list of tag names (array of strings, not required)

  • duronly: should Toggl show the start and stop time of this time entry? (boolean, not required)

  • at: timestamp that is sent in the response, indicates the time item was last updated

See this doc for the latest properties available for the API: https://github.com/toggl/toggl_api_docs/blob/master/chapters/time_entries.md

Data in this object will override the workspace and project properties for data.wid and data.pid

Usage Examples

Finding your workspace IDs

Use:

grunt toggl:MYTASK:workspaces

To get a JSON list of workspaces. MYTASK should be whatever task you have configured, since you still need a valid API Key to get the workspaces.

OR just run the task without a workspace set. It will list your workspaces by default.

Finding your project IDs

Use:

grunt toggl:MYTASK:projects

To get a JSON list of projects in the configured workspace. Your task needs to have a Workspace ID properly setup in order to use this argument (valid workspace or wid set in the options).

Stop the current task

Use:

grunt toggl:MYTASK:stopCurrent

To stop the current task timer. This will call the API to find out if there is a current timer running. If there is, another call is made to stop it.

OR add this to your Gruntfile.js

grunt.registerTask('toggl:stop', ['toggl:default:stopCurrent']);

and you will be able to simply call

grunt toggl:stop

Default Options

grunt.initConfig({
  toggl: {
    options: {
      settingsFile: '.toggl',
      workspace: null,
    }
  },
});

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

TODO

  • debug option that deletes time entries as soon as they're created.

Release History

- 2015-02-22   v1.0.0    [CHANGED]  dependency bump
- 2015-02-21   v0.3.0    [CHANGED]  support grunt >=0.4.4 in package.json
- 2014-04-29   v0.2.0    [ADDED]    argument for listing projects in a workspace
- 2014-04-29   v0.2.0    [ADDED]    argument for listing projects in a workspace
                         [CHANGED]  arg for listing workspaces
- 2014-04-28   v0.1.1    Alpha READY. It works.
- 2014-04-28   v0.1.0    Work in progress, not ready.