README

A simple CLI tool that interacts with the Timely API to fetch the relevant data and calculate your overtime balance from it.

Built with Laravel Zero.

Requirements

• PHP ^8.5
• Composer
• A Timely OAuth application (details below)

Installation

This app is bundled into a standalone PHAR you can download via composer:

composer global require webhubworks/overtimely

Confirm installation:

overtimely

Setup

Your Timely accounts admin needs to configure a new OAuth2 application with an OOB redirect URI.
You'll need the following from them to use this tool:

• Application ID (Client ID)
• Application Secret (Client Secret)
• Redirect URI
• Account ID

Once you've received these details, run the following command and follow the instructions:

overtimely config:setup

Usage

Run overtimely to get a list of the available commands and use the --help option with a command to see its description, arguments and options.

Date Formats

Any and all date inputs accept all formats supported by PHP. This enables even relative formats like for example "last friday" to be used as option values and default settings.

Fetching Modes

Throughout the app you will find it referencing fetching modes.

The app features two different modes for fetching your logged hours from Timely's API, those being:

Totals

Fetches Timely's reports, which directly include the total duration of logged hours for a given period. Aggregated by Timely based on time entry durations.

Events

Fetches individual events (aka time entries with their individual timestamps) for a given period and merges overlapping timestamps.
This takes much longer. But it solves the issue of parallel timestamps counting fully towards the total working time.

Note

In essence:
Two parallel timestamps of one hour will result in the Totals mode counting two hours, while the Events mode will only count one hour of working time. Use whichever mode is applicable to your situation.

Development

Local development

To run the app locally, you have to prefix it with PHP while in the project directory:

php overtimely

You can use an .env file to set/override the user configuration values which are set by the config:setup and config:set commands. Have a look at the .env.example file to see the available environment variables.

Releasing a build

This app is distributed as a PHAR, so you need to make a new build including your changes to actually release them.

To facilitate this, the project has a Makefile. So after you have committed all of your changes (remember to update the changelog as well!), you can run the following:

make release VERSION=<build_version>

This will build, commit, tag and push a new PHAR all in one go.

For deciding on the correct build_version to use: This project adheres to Semantic Versioning.