Publish WebAPI client library for NPM

[YaSuenag]

Pull Request

Issue Number: #590

Summary

Publish WebAPI client library for NPM

Changes

This PR adds new workflow to generate WebAPI client library for NPM.
The artifact would be published to GitHub Packages, so the developer can integrate the library into their own project from GitHub Packages via npm install.
(Note that the developer should set GitHub PAT. See GitHub document for details.)

Client library generation happen via both release workflow and workflow dispatch. After this PR, Both Java and NPM library would be pushed into GitHub Packages:

Updated: 2024-11-27

I and @danuw discussed about this PR in weekly meeting, we agreed that we need to improve workflow for client generation.
This PR proposes following workflows:

Publish new release (GitHub Release)
    |
(in 4-release.yaml)
    1. Detect current WebAPI version from the latest WebAPI container image
    2. Publish new container to GHCR
    3. Detect NEW latest WebAPI version from new container image generated in 2.
    4. If the version in 3. is different from 2., client library generation will be started (4.a-generate-webapi-clients.yaml) because it implies WebAPI version has been updated.

(in 4.a-generate-webapi-clients.yaml)
    1. Detect new WebAPI version
    2. Generate and push client libraries to GitHub Packages with the latest label - Java and NPM will process in parallel
        - API doc will also generate in this phase
    3. Create PR for API docs to merge dev branch

You can see PR for API docs after 4.a-generate-webapi-clients.yaml . CASDK mainteners should approve/merge this ASAP.
Example of the PR: YaSuenag#2

Note that this PR fixed to specify OpenAPI document title and version from CarbonAwareVariablesConfiguration. It relates to the comment from @danuw in #471.

Checklist

• Local Tests Passing?
• CICD and Pipeline Tests Passing?
• Added any new Tests?
• Documentation Updates Made?
• Are there any API Changes? If yes, please describe below.
• This is not a breaking change. If it is, please describe it below.

Are there API Changes?

No

Is this a breaking change?

No

Anything else?

I recommend to run .github/workflows/4.a.1-generate-webapi-client-npm.yaml manually after merging this PR to generate client libraries - API version does not synchronize CASDK releases.

This PR Closes #590

[danuw]

@YaSuenag can we try a more recent version (to avoid more painful updates in the future and ensure we stay up to date if possible)

[danuw]

Notes from our conversation about the flow of changes following new client libraries and at what point we save the changes in history so we can have consistency on following releases (history of client libraries etc...)

--- Draft Notes ---

new changes -> dev

dev -> main -> release workflow -> container package

Container version - is SDK version
Doc is indexed on latest version of code


on new container package -> check api version
- If API version version is updated, client api for java, npm etc... will need to be updated
- If API version not updated in new container release, we do not need to update clients libraries 

If API version is updated and we need new client libraries to be generated, what is the impact on documentation and published documentation?


----
start workflow to generate API document -> create PR to dev -> if PR approved, doc is merged into dev branch and new PR to main -> if PR to main approved -> workflow creates a new client library and pushes to github

SDK v1.8: latest
CLib v1.0 : latest

----
start workflow to generate API document v1.1 -> workflow has automated tests for new client library v1.1:pre
 (1) workflow creates a new client libraries and pushes to github -> 1.1 marked as latest
 (2) publish container 
 (2) publish documentation
 (3) automated test & mark latest
 (4) create PR to dev (to keep history) -> if PR approved, doc is merged into dev branch 

[YaSuenag]

@danuw
I updated this PR to follow the discussion in weekly meeting. See PR description for details.

[YaSuenag]

I added client example in TS to this PR: https://github.com/YaSuenag/carbon-aware-sdk/tree/pr/generate-npm-client/samples/npm-client

It does not work yet because it depends the library provided by GitHub Packages in Green-Software-Foundation namespace. It should work after client libraries are published (new version is released).

[danuw]

LGTM - and thank you for the documentation piece

[YaSuenag]

@danuw
Workflows for generating client libraries were failed due to HTTP 504 error: https://github.com/Green-Software-Foundation/carbon-aware-sdk/actions/runs/12252465677/job/34179170208

It might fail due to outage of Maven Central Repository: https://status.maven.org/
I found known issue about this: OpenAPITools/openapi-generator-cli#680

So can you retry after Maven Central recovers?
Note that you should set tag to pre manually to generate because API version number (1.0.0) is specified for OpenAPI doc in this PR.

[YaSuenag]

Maven Central has been resumed (when I write this post, at least 😁), then these workflows have succeeded on my forked repo.

[YaSuenag]

@danuw
Thank you for re-run the workflow. But NPM client was not generated because invalid API version number (1.0).

1.0 comes from the latest (v1.6.1 so far) container. It should be 1.0.0, and I updated so that it would in this PR. Thus you should kick 4.a-generate-webapi-clients.yaml with pre tag as above comment.

So can you run the workflow again with pre tag? Thanks!

[danuw]

Thank you, it looks like it was successful now. Thank you @YaSuenag

[YaSuenag]

Thanks a lot @danuw ! All of workflows (for client libs) succeeded - I could use it in other project 👍 danuw/if-casdk-plugin#4