TypeScript library Generation

[mphuff]

Opening this PR right now for validation of the automation as well as to get initial feedback.

[NodeJSmith]

@mphuff Haven't had a chance to look at the code in detail but so far I think I'm okay with this idea. I want to double check that publishing to Pypi and the readthdocs stuff still work as expected (not sure if you are able to validate that or not).

Should we plan to add a docs site for the TS version of the code as well? Do you need to add a workflow for publishing to npm?

[NodeJSmith]

Also, make sure you account for some of the crappier edges of the data model, like active_time_seconds from the v2 workout model and maxHr from the telemetry

        # from workout.py
        if v2_workout:
            data["active_time_seconds"] = v2_workout.active_time_seconds

        telemetry: dict[str, Any] | None = data.get("telemetry")
        if telemetry and "maxHr" in telemetry:
            # max_hr seems to be left out of the heart rate data - it has peak_hr but they do not match
            # so if we have telemetry data, we can get the max_hr from there
            data["details"]["heart_rate"]["max_hr"] = telemetry["maxHr"]

Also, i think we can improve some of the python scripts by using uv, but that can be something to add later.

[mphuff]

I plan to make sure all python scripts can be leveraging uv yes. I am still finessing the "AI automated typescript conversion" workflow (nearly there, just a few edge cases).

Happy to discuss further though if this is something you want in the core library; I'm also ok if you think it muddies the cleanliness too much and I can maintain my own copy but keep me honest. You're the owner so want you to have the final say in it.

My general approach here:

1. Change comes in to the python code
2. Runs automated tests for python code
3. Runs linting for python and existing typescript
4. IF (due to cost primarily) change is >3 files and/or > 50 lines of code, runs the CR through Claude for automated typescript code generation, and that will be cut to a CR (will require you and I to coordinate a secret being added to the repository)
5. Runs tests on typescript

[mphuff]

@mphuff Haven't had a chance to look at the code in detail but so far I think I'm okay with this idea. I want to double check that publishing to Pypi and the readthdocs stuff still work as expected (not sure if you are able to validate that or not).

Should we plan to add a docs site for the TS version of the code as well? Do you need to add a workflow for publishing to npm?

Docs site for TS yes - I incorporated typedoc but I don't particularly like the format so I may play with that more.
Yes will want to add a workflow to publish to NPM but I think I'd want to keep version in lockstep so I'll look at how you're doing with existing versioning and pypi publish and incorporate accordingly a separate workflow (or part of existing one). I've got an npm account we can use or we can use yours if you've gone one; not married to how we do that.

[mphuff]

@mphuff Haven't had a chance to look at the code in detail but so far I think I'm okay with this idea. I want to double check that publishing to Pypi and the readthdocs stuff still work as expected (not sure if you are able to validate that or not).
Should we plan to add a docs site for the TS version of the code as well? Do you need to add a workflow for publishing to npm?

Docs site for TS yes - I incorporated typedoc but I don't particularly like the format so I may play with that more. Yes will want to add a workflow to publish to NPM but I think I'd want to keep version in lockstep so I'll look at how you're doing with existing versioning and pypi publish and incorporate accordingly a separate workflow (or part of existing one). I've got an npm account we can use or we can use yours if you've gone one; not married to how we do that.

@NodeJSmith - After working through this more, I'm wondering if you have a strong opinion here or not.

I had originally thought about having Claude just auto-generate the TypeScript library on change. More I think about it, I think I'm talking myself out of this approach and rather than combining into libraries, I'll maintain the otf-api-ts library, making it VERY clear in the README that I do not back-port to Python so as to not muddy waters, but rather as I need new version updates OR I have pushed a change into python that I need ported to TypeScript, I'll just cut a new build of the TypeScript. I'm running into a lot of consistency problems no matter the prompting right now and as much as the glory hole of AI-generated code is, I'm not sure it's worth much more time.

My problem I'm having is it doesn't know when to just make edits vs. cut whole files out as the library evolves and context grows; and I don't know that I want to continue to engineer much more on this vs. get back to actual feature development in the products :)

[mphuff]

@NodeJSmith - Closing this PR in favor of a new one I'll be opening up. It's a much cleaner overall implementation and I think the more maintainable version longer-term.

[mphuff]

@NodeJSmith - Closing this PR in favor of a new one I'll be opening up. It's a much cleaner overall implementation and I think the more maintainable version longer-term.

@NodeJSmith - i'm aiming to have a new PR this weekend. The only change in your repository would be generating the actual schema asset that would be part of the release (and I will have a PR for this). The TS library that I will check in will cross validate the generated records from the Python library and the TS library as an integration test. I'm working out a few remaining edge cases between the initial implementations, but I am nearly there; just haven't had a lot of time this week.

This is a much cleaner and stable implementation, and it actually ties the underlying TS library for a variety of pieces to your released version. This is both for pulling in the generated model file as well as running a python integration test to pull real data via your released library asset.

My maintenance plan will be to run the diff between releases through [name my favorite AI tool of the week] and commit my own PR and release to npmpm. Your library should remain the source of truth and will be credited accordingly.

[NodeJSmith]

That sounds good to me, I'll try to get to the review quickly so as not to slow you down 👍