JSON “API” to allow custom integrations

[wAuner]

For macOS there is a great productivity tool called alfred. Once the core functionality of klog has matured, I think it would be cool to add an alfred integration. If I find the time, I‘d be happy to help with that.
All that should be needed would probably be an option that returns the output as json.

This way mac users could call klog from anywhere instantly without opening the terminal.

[jotaen]

Awesome idea! Have also been wondering about use-cases for a programmatic API already (JSON or the like). That would allow for some interesting extensions indeed.

Cool to know that you’d be potentially interested in this. I’ll keep this ticket open, hit me up whenever you find the time and leisure to do something.

[jotaen]

This topic came up quite a few times now. I think having such an API would be a cool enabler to make klog more hackable and allow people build their own workflows around it, without having to write their own parser and evaluators. I changed the title to reflect the more “generic” nature of this idea.

[vladdeSV]

I believe that a JSON API would be a good thing.

That would help me when I implement a language server for my syntax highlighter (à la vladdeSV/vscode-klog#7).

[jotaen]

Just a sketch how the JSON output could look:

Happy path

{
  "records": [
    {
      "date": "2020-01-01",
      "should_total": "8h!",
      "should_total_mins": 480,
      "summary": "First day at new #job",
      "tags": ["job"],
      "total": "7h15m",
      "total_mins": 435,
      "entries": [
        {"type": "range",
         "start": "9:00",
         "start_midnight_offset_mins": 540,
         "end": "17:00",
         "end_midnight_offset_mins": 1020,
         "summary": null,
         "tags": [],
         "total_mins": 460},
        {"type": "duration",
         "time": "-45m",
         "time_mins": -45,
         "summary": "Lunch break",
         "tags": [],
         "total_mins": -45}
      ]
    }
  ],
  "errors": null,
}

Parsing errors

{
  "records": null,
  "errors": [{
    "line": 3,
    "column": 0,
    "length": 8,
    "message": "Malformed date, bla bla bla"
  }]
}

[vladdeSV]

A few thoughts in no particular order:

• In the error object, maybe the position could be renamed to column?
• Although I do not have a better alternative right now, I am not completely satisfied with "start/end_midnight_offset_mins".
• A suggestion would be to move "should-total" to its own category "properties": { "should-total": { /* data */ } }. I think that should be the case as long as the spec (potentially) allows multiple properties.
• Another thing which I do not know where I stand is: Should the API return both records and errors if they can never both contain data at the same time? I believe it will be simpler to check if an error occurred by doing a null check instead of checking if a key exists.
• For ranges, what will start and end be when targeting adjacent days? "17:00>" or just "17:00"?

[jotaen]

Excellent, thanks for your thoughts! 🎉

• 👍 Ah yes, column is better. (Updated JSON above.)
• Are you unsatisfied with start_midnight_offset_mins because it’s clunky or because it lacks clarity? For me it’s the former, but I value clarity more and also don’t have any better idea…
• Hm, not sure about the properties: I agree it’s more “systematic”, but on the other hand I think flat structures are easier to work with. You could then also argue it should be "evaluation":{"total":500} etc. In the end I guess it shouldn’t matter as much, as long as it’s clearly documented. (Unrelated: I might ditch the concept of “properties”.)
• records/errors: for API output I personally like to be strict and, if feasible, generate “complete” data structures with explicit null values. I think it makes the output a bit more self-documenting, and we don’t have to worry about bandwidth in this case.
• Good question! My initial idea was to offer two representations of the time-related values, a string for display purposes and an integer for programatic processing. The string value would be what you see in the file, so regarding your question e.g. "<23:00", the corresponding integer would be -60. I was also considering "23:00" with an additional is_yesterday/is_previous_day bool flag, but wasn’t sure about that. If you have thoughts on this I’d be happy to hear.

[jotaen]

I’m pretty excited about this idea, so I already got something to work this morning. If someone wants to take a look, I published a pre-release for testing here: https://github.com/jotaen/klog/releases/tag/v1.6-beta1. Just run klog json some-file.klg and it will dump the JSON to Stdout.

Instead of start_midnight_offset_mins I just chose start_mins now, because that somehow felt better. Maybe it’s fine as along as the documentation is clear what it is?

I wouldn’t expect major changes anymore, maybe rather a few adjustements or tweaks here and there. So could be ready to go on the weekend or so.

cc @tecunningham

[jotaen]

klog json has landed in v1.6: https://github.com/jotaen/klog/releases/tag/v1.6

• Sorting and filtering is supported as it is in the other commands.
• I didn’t document the output structure yet, but it should be fairly self-explanatory. It can be best explored via klog json --pretty file.klg.
• Also, you can now pipe input to klog from stdin, which should make it easier to run it as subprocess from somewhere else. (echo '2020-01-01\n\t1h' | klog json on the CLI.)

I’ll close this ticket here, but feel free to open new ones when you find things missing or not working.

[jotaen]

@wAuner, since the inital request was about alfred actually: should you get around to building an alfred extension / workflow, please let me know so I can link it from the docs. I suppose these extensions won’t (or can’t) be part of the klog distributable, but I would love to reference them 😊