Wakamonth - hours reporting tool

[jvanveen]

Generating declarable hours reports using Wakapi with "Wakamonth"; a simple script that uses the Wakapi API to generate an Excel sheet that lists worked hours grouped per branch. Not sure if it's any good yet, but it is a start :) See https://github.com/bitstillery/wakamonth

Any thoughts about the reliability, improvements or anything else? Somehow it still has a lot of hours grouped on Unknown branch. Any idea how to debug this properly? I'm using the VScode plugin and the browser plugin (Firefox)

[muety]

Amazing little project, thanks for sharing! 👏 It's very cool to see tooling evolve around Wakapi.

Regarding your question:

Somehow it still has a lot of hours grouped on Unknown branch. Any idea how to debug this properly?

When tracking browsing data using the WakaTime Firefox / Chrome plugin, the branch and language fields will be empty (-> "unknown") as there is no such thing as a "branch" for a website obviously.

I tried the tool and it works very well! A few remarks from my side (knowingly, that the tool is, of course, still work in progress):

• Probably planned, but you'll likely want to pass the target project as a command-line argument as well
• From my understanding, you're currently rounding to hour-precision. Would be cool to be able to specify the "granularity" of reporting, e.g. half- or quarter-hourly
• I'd suggest using the WakaTime compat endpoint (see here, here). It exposes the same data, but in a slightly different format. When querying against that endpoint, you'll implicitly get support for WakaTime (not only Wakapi) as well, which makes you're tool even more useful.

And, of course, as a disclaimer: coding time tracked by Wakapi is only a rough proxy or indicator of the actual amount of work spent on a project / on a feature. It's only an estimate and definitely not legally binding, so people should keep that in mind when using it for billing reports / invoices.

[jvanveen]

Hi @muety,

Thanks for the feedback and suggestions! I added the target project as a config directive (forgot about that one) and added a precision parameter (60/30/15) for granularity. The disclaimer was added to the Readme, so people are warned up-front. I tried to use the compat endpoint, but Wakapi crashed after I called the endpoint like:

https://wakapidomain.org/api/compat/wakatime/v1/users/jvanveen/summaries?end=2023-12-31&start=2023-12-01&project=manhattan

About the unknown hours; I thought the plugin would only register whitelisted sites; e.g.

Logging Style: Only whitelisted sites
http://localhost:9000@@myproject
http://localhost:9001@@myproject

Shouldn't it log only hours on project/branch, based on <<LAST_BRANCH>>/<<LAST_PROJECT>>?
I forgot to mention I'm also using the zsh plugin for Wakatime, which may also cause some unknown time.

[muety]

but Wakapi crashed after I called the endpoint

That definitely shouldn't be happening. Could you please post the error message with which the server had crashed?

Shouldn't it log only hours on project/branch, based on <<LAST_BRANCH>>/<<LAST_PROJECT>>?

Yes, you're right! The branch field of a heartbeat sent from the browser plugin will be set to the last branch of that heartbeat's project. This requires a project to be explicitly specified for the site (using the @@), because Wakapi does intentionally not support the <<LAST_PROJECT>> feature (see our previous discussion). So effectively, you'll only get a non-unknown branch for site that you have whitelisted and defined a project mapping for.

Could you possibly have a look into your database's heartbeats table and see where most unknown branches (branch column being set to either empty string (""), NULL or "<<LAST_BRANCH>>") come from? Would be interesting to know if they result from a bug in Wakapi or if it's the editor plugin's fault.

Also, which version of the browser plugin are you using?

Either way, thanks a lot your efforts with wakamonth!

[muety]

Port 587 is usually used for STARTTLS, in which case you'd set tls: false. You shouldn't have to reset your password or regenerate summaries after an update. Did you perhaps accidentally delete your database or so?

[muety]

Those parameters shouldn't be irrelevant for you, I think. But maybe check your browser console for errors.

[jvanveen]

The reporting was empty because we just changed years, and I didn't add a year parameter yet. Best wishes for 2024 by the way :)
Gladly, the reporting data still works using the API key; only the frontend login usiny my credentials doesn't. The user has a password set($argon...), and the login itself seems to be fine (just returns a 401 as expected)

[muety]

Very strange. Did you change your salt (security.password_salt / WAKAPI_PASSWORD_SALT) after the update?

[jvanveen]

Ok, problem solved. I just had to restart the systemd service, and then the login worked as expected. Maybe a write permission error somewhere; I'm not sure. I'll see if I can update the endpoint to the wakatime one later this week. Thanks for the help!

[jvanveen]

Alright, I tested the compat endpoint and adapted the data format to the report. Also modified the config a bit, so it is a bit more flexible. Should work with Wakatime as well, but I don't have an account to test with. Basic setup should be as simple now as:

wget -O ~/.wakamonthrc https://raw.githubusercontent.com/bitstillery/wakamonth/main/.wakamonthrc.example
npx @bitstillery/wakamonth -y 2024 -m 1 report

[muety]

Very cool! 🙌 Only a few more minor remarks:

• There is a double-quote missing in the default config file
• I think it would be convenient if your could pass the project as a command-line argument, so you wouldn't have to modify the config file every time you request stats for a different project
• Initial setup would be even more convenient if the API URL and -key were automatically read from the .wakatime.cfg file

[jvanveen]

Thanks for the feedback! All valid and useful changes. Haven't thought about reusing an existing .wakatime.cfg yet! This would probably be an init command. I'll move the project to commandline. Made a start to support multiple outputs(stdout/xlsx). Not sure whether other formats might be useful.

[jvanveen]

Small blogpost about the whole process: https://bitstillery.com/2024/01/09/wakamonth-hours-reporting-tool/

[muety]

Awesome! I added your blog post to the community contributions section.

[jvanveen]

I applied the wakatime.cfg changes, but it seems that it still needs a backend config parameter?
In my wakatime.cfg, I have a Wakapi endpoint like:

# Wakapi
api_url = https://wakapi.<DOMAIN>/api
# Wakatime
api_url=https://api.wakatime.com/api

The endpoints are:

# Wakapi
/compat/wakatime/v1/users/${user.id}/summaries
# Wakatime
/v1/users/${user.id}/summaries

Should I use api_url = https://wakapi.<DOMAIN>/api/compat/wakatime in wakatime.cfg instead of https://wakapi.<DOMAIN>/api? In that case the endpoints are the same, and I can loose the backend parameter as well.

[muety]

Should I use api_url = https://wakapi.<DOMAIN>/api/compat/wakatime in wakatime.cfg instead of https://wakapi.<DOMAIN>/api?

Yes, exactly.

[jvanveen]

I just checked, but after I did update the api_url in wakatime.cfg to api/compat/wakatime, I didn't receive any data anymore (using the vscode plugin). Switching back to /api restores this. Not sure what went wrong; I'll try to debug it later. By the way, I moved further work on Wakamonth to this repo (https://codeberg.org/garage44/wakamonth)