Publish WebAPI client library for NPM

.github/workflows/4-release.yaml

@@ -67,6 +67,7 @@ jobs:
     permissions:
       contents: write
       packages: write
+      pull-requests: write
     with:
       # We cannot use environment variables here due to workflow limitation.
       # https://docs.github.com/en/enterprise-cloud@latest/actions/using-workflows/reusing-workflows#limitations

.github/workflows/4.a-generate-webapi-clients.yaml

@@ -31,6 +31,7 @@ on:
 permissions:
   contents: write
   packages: write
+  pull-requests: write
 
 jobs:
   detect-api-version:
@@ -46,3 +47,43 @@ jobs:
     with:
       image: ${{ needs.detect-api-version.outputs.image }}
       apiver: ${{ needs.detect-api-version.outputs.apiver }}
+
+  generate-npm-client:
+    needs: detect-api-version
+    uses: ./.github/workflows/4.a.1-generate-webapi-client-npm.yaml
+    with:
+      image: ${{ needs.detect-api-version.outputs.image }}
+      apiver: ${{ needs.detect-api-version.outputs.apiver }}
+
+  push-apidocs:
+    runs-on: ubuntu-latest
+    needs:
+      - detect-api-version
+      - generate-java-client
+      - generate-npm-client
+    env:
+      DOCPATH: casdk-docs/static/client-apidocs/${{ needs.detect-api-version.outputs.apiver }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: dev
+      - name: Extract Javadoc
+        uses: actions/download-artifact@v4
+        with:
+          name: javadoc
+          path: ${{ env.DOCPATH }}/java
+      - name: Extract TypeDoc
+        uses: actions/download-artifact@v4
+        with:
+          name: typedoc
+          path: ${{ env.DOCPATH }}/npm
+      - name: Create PR for Client API docs
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: "Add Client API documents for WebAPI ${{ needs.detect-api-version.outputs.apiver }}"
+          branch: gha/pr/webapidoc-${{ needs.detect-api-version.outputs.apiver }}
+          delete-branch: true
+          title: "Add Client API documents for WebAPI ${{ needs.detect-api-version.outputs.apiver }}"
+          body: |
+            This PR has been created by 4.a-generate-webapi-clients.yaml due to WebAPI version update.

.github/workflows/4.a.1-generate-webapi-client-java.yaml

@@ -54,31 +54,3 @@ jobs:
         with:
           name: javadoc
           path: work/target/apidocs
-
-  push-javadoc:
-    needs: generate-java-client
-    concurrency: push-to-doc-website
-    runs-on: ubuntu-latest
-    env:
-      DOCPATH: casdk-docs/static/client-apidocs/${{ inputs.apiver }}/java
-    permissions:
-      contents: write
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Prepare
-        run: mkdir -p ${{ env.DOCPATH }}
-      - name: Download Javadoc
-        uses: actions/download-artifact@v4
-        with:
-          name: javadoc
-          path: ${{ env.DOCPATH }}
-      - name: Push Javadoc
-        run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add ${{ env.DOCPATH }}
-          git commit -m "Add Javadoc for WebAPI ${{ inputs.apiver }}"
-          git push origin ${{ github.ref_name }}
-        env:
-          GITHUB_TOKEN: ${{ github.token }}

.github/workflows/4.a.1-generate-webapi-client-npm.yaml

@@ -0,0 +1,65 @@
+name: 4.a.1-Generate WebAPI client library for NPM
+
+on:
+  workflow_call:
+    inputs:
+      image:
+        required: true
+        type: string
+      apiver:
+        required: true
+        type: string
+
+jobs:
+  generate-npm-client:
+    runs-on: ubuntu-latest
+    services:
+      webapi:
+        image: ${{ inputs.image }}
+        ports:
+          - 8080:8080
+        options: >-
+          --health-cmd "curl -sS http://localhost:8080/health"
+          --health-interval 3s
+          --health-timeout 5s
+          --health-retries 5
+    permissions:
+      packages: write
+    env:
+      API: http://localhost:8080/api/v1/swagger.yaml
+    steps:
+      - name: Setup Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          registry-url: https://npm.pkg.github.com
+      - name: Prepare
+        run: |
+          mkdir work
+          npm install -g @openapitools/[email protected]
+      - name: Generate client library
+        run: |
+          echo -n '{"npmName": "@${{ github.repository_owner }}/casdk-client", "npmVersion": "${{ inputs.apiver  }}", "licenseName": "MIT", "gitUserId": "${{ github.repository_owner }}", "gitRepoId": "' > config.json
+          echo -n "${{ github.repository  }}" | sed -e 's|^.\+/||' >> config.json
+          echo -n '", "npmRepository": "https://npm.pkg.github.com"}' >> config.json
+          openapi-generator-cli generate -i ${{ env.API }} -g typescript-axios -o work -c config.json
+        shell: bash
+      - name: Publish NPM library
+        working-directory: work
+        run: |
+          npm install
+          npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ github.token }}
+      - name: Setup TypeDoc
+        run: npm install -g typedoc
+      - name: Generate documents
+        working-directory: work
+        run: |
+          echo '{"out": "docs", "excludePrivate": true, "excludeProtected": true, "excludeExternals": true, "includeVersion": true}' > ../typedoc.json
+          npx typedoc --options ../typedoc.json --entryPoints index.ts
+      - name: Upload TypeDoc
+        uses: actions/upload-artifact@v4
+        with:
+          name: typedoc
+          path: docs

.gitignore

@@ -34,4 +34,5 @@ src/data/location-sources/custom-azure-zones.json
 # exclude artifacts on java-client example
 samples/java-client/target
 
-casdk-docs/docs/samples/*
+casdk-docs/docs/samples/*
+node_modules/

casdk-docs/sidebars.js

@@ -14,20 +14,34 @@
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
-  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
-
-  // But you can create a sidebar manually
-  /*
   tutorialSidebar: [
-    'intro',
-    'hello',
     {
-      type: 'category',
-      label: 'Tutorial',
-      items: ['tutorial-basics/create-a-document'],
+      type: 'autogenerated',
+      dirName: '.'
     },
-  ],
-   */
+    {
+      type: 'category',
+      label: 'API references for WebAPI client libraries',
+      items: [
+        {
+          type: 'category',
+          label: 'WebAPI 1.0.0',
+          items: [
+            {
+              type: 'link',
+              label: 'Java',
+              href: 'https://carbon-aware-sdk.greensoftware.foundation/client-apidocs/1.0.0/java/'
+            },
+            {
+              type: 'link',
+              label: 'NPM',
+              href: 'https://carbon-aware-sdk.greensoftware.foundation/client-apidocs/1.0.0/npm/'
+            }
+          ]
+        },
+      ]
+    }
+  ]
 };
 
 module.exports = sidebars;

samples/npm-client/.npmrc

@@ -0,0 +1,2 @@
+//npm.pkg.github.com/:_authToken=${GH_TOKEN}
+@Green-Software-Foundation:registry=https://npm.pkg.github.com

samples/npm-client/README.md

@@ -0,0 +1,66 @@
+# NPM Client Example
+
+This folder contains an example for WebAPI client in NPM. Client library would be pulled from [GitHub Packages](https://github.com/orgs/Green-Software-Foundation/packages?repo_name=carbon-aware-sdk).
+
+TypeDoc is [here](https://carbon-aware-sdk.greensoftware.foundation/client-apidocs/1.0.0/npm).
+
+## Requirements
+
+- WebAPI instance
+  - See the [Overview](../../docs/overview.md#publish-webapi-with-container) if you'd like to start it on container.
+- Node.js 18 or later
+
+## Client code
+
+[index.js](index.js) is an example program to call WebAPI endpoint. It calls all of endpoints, and shows the result.
+
+Following methods are available:
+
+- `processBestEmissionsDataByLocations`
+  - Call /emissions/bylocations/best
+  - Gather the best emission data for west/central/east US yesterday.
+- `processEmissionsDataByLocations`
+  - Call /emissions/bylocations
+  - Gather emission data for west/central/east US yesterday.
+- `processEmissionsDataByLocation`
+  - Call /emissions/bylocation
+  - Gather emission data for westus yesterday.
+- `processCurrentForecastData`
+  - Call /emissions/forecasts/current
+  - Gather forecast data for westus.
+- `processForecastBatchData`
+  - Call /emissions/forecasts/batch
+  - Gather forecast data for westus.
+- `processAverageData`
+  - Call /emissions/average-carbon-intensity .
+  - Gather average data for westus yesterday.
+- `processAverageBatchData`
+  - Call /emissions/average-carbon-intensity/batch
+  - Gather average data for westus yesterday.
+
+## How it works
+
+### 1. Set WebAPI endpoint
+
+You need to set base URL of WebAPI endpoint in `index.ts`. `http://localhost:8080` is set by default.
+
+```typescript
+const conf = new Configuration({basePath: 'http://localhost:8080'});
+```
+
+### 2. Install required packages
+
+You have to run `npm install` at first. CASDK client module would be downloaded from GitHub Packages, so you need to set GitHub Parsonal Access Token. You can set it to `GH_TOKEN` environment variable used in [.npmrc](.npmrc).
+
+If you have not yet got GitHub PAT, see [this guide](https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+
+```sh
+GH_TOKEN=<GitHub PAT> npm install
+```
+
+### 3. Run
+
+```sh
+npx ts-node index.ts
+```