refactor(frontend): generate API react-query helpers with Orval DEV-893 (#6083)

### 💭 Notes

Generate react-query helpers from API with Orval. By it's own does
nothing. See these few refactors, the rest is for now unused generated
files:
- `jsapp/js/api.ts`
- `package.json`
- `package-lock.json`

Configuration is split across these files:
- `orval.config.js`
- `jsapp/js/api/orval.mutator.ts`
- `jsapp/js/api/orval.operationName.ts`
- `scripts/generate_api.sh`
- `.github/workflows/openapi.yml`

See other refactor PRs that use these helpers to call API:
- #6090

### 👀 Preview steps

1. run kobo-install locally
2. `./run.py -cf run --rm kpi ./scripts/generate_api.sh` to re-generate
helpers
3. notice that helpers are regenerated
4. click around so that some APIs are called the old way
5. notice that it still works and the refactors didn't break anything

Author: Akuukis

.github/workflows/openapi.yml

@@ -4,7 +4,9 @@ name: openapi
 
 on: workflow_call
 jobs:
-  build:
+
+
+  drf-spectacular:
     runs-on: ubuntu-24.04
     env:
       DATABASE_URL: postgis://kobo:kobo@localhost:5432/kpi_test
@@ -40,33 +42,85 @@ jobs:
           - 6379:6379
     steps:
 
-    - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install pip-tools
+        run: python -m pip install pip-tools==7.\*
+
+      - name: Update Debian package lists
+        run: sudo DEBIAN_FRONTEND=noninteractive apt-get -y update
+
+      - name: Install Debian dependencies
+        # All about YAML line breaks: https://stackoverflow.com/a/21699210
+        run: >-
+          sudo DEBIAN_FRONTEND=noninteractive apt-get -y install
+          gdal-bin gettext libproj-dev postgresql-client ffmpeg
+          gcc libc-dev build-essential
+
+      - name: Install Python dev dependencies
+        run: pip-sync dependencies/pip/dev_requirements.txt
 
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.python-version }}
+      - name: Generate OpenAPI with drf-spectacular
+        run: ./scripts/generate_api.sh --skip-orval
 
-    - name: Install pip-tools
-      run: python -m pip install pip-tools==7.\*
+      - name: Fail on uncommitted OpenAPI changes
+        run: |
+          git diff
+          git diff-index --exit-code HEAD
 
-    - name: Update Debian package lists
-      run: sudo DEBIAN_FRONTEND=noninteractive apt-get -y update
 
-    - name: Install Debian dependencies
-      # All about YAML line breaks: https://stackoverflow.com/a/21699210
-      run: >-
-        sudo DEBIAN_FRONTEND=noninteractive apt-get -y install
-        gdal-bin gettext libproj-dev postgresql-client ffmpeg
-        gcc libc-dev build-essential
+  orval:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.18.1  # version that's pinned in Dockerfile for kpi release. FYI v22 doesn't work out of box.
+          check-latest: true # download newer semver match if available
+          cache: 'npm'
+
+      - name: Identify resolved node version
+        id: resolved-node-version
+        run: echo "NODE_VERSION=$(node --version)" >> "$GITHUB_OUTPUT"
+      - name: Add "Node ${{ steps.resolved-node-version.outputs.NODE_VERSION }}" to summary
+        run: echo "22 → **${{ steps.resolved-node-version.outputs.NODE_VERSION }}**" >> "$GITHUB_STEP_SUMMARY"
+
+      # Cache: Use cache for node_modules
+      #        Keyed on os, node version, package-lock, and patches
+      - uses: actions/cache@v4
+        name: Check for cached node_modules
+        id: cache-nodemodules
+        env:
+          cache-name: cache-node-modules
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-build-${{ env.cache-name }}-node-${{ steps.resolved-node-version.outputs.NODE_VERSION }}-${{ hashFiles('**/package-lock.json', 'patches/**/*.patch') }}
+
+      # Cache hit:  If the cache key matches,
+      #             /node_modules/ will have been copied from a previous run.
+      #   (Run the post-install step, `npm run copy-fonts`)
+      - name: Run copy-fonts (if using cached node_modules)
+        if: steps.cache-nodemodules.outputs.cache-hit == 'true'
+        run: npm run copy-fonts
 
-    - name: Install Python dependencies
-      run: pip-sync dependencies/pip/dev_requirements.txt
+      # Cache miss: If node_modules has not been cached,
+      #             `npm install`
+      #   (This includes `npm run copy-fonts` as post-install step)
+      - name: Install JavaScript dependencies (npm install)
+        if: steps.cache-nodemodules.outputs.cache-hit != 'true'
+        run: npm install
 
-    - name: Generate OpenAPI
-      run: ./scripts/generate_openapi_schemas.sh
+      # Check for TypeScript errors
+      - name: Generate react-query helpers with Orval
+        run: npm run build:orval
 
-    - name: Fail on uncommitted OpenAPI changes
-      run: |
-        git diff
-        git diff-index --exit-code HEAD
+      - name: Fail on uncommitted react-query helper changes
+        run: |
+          git diff
+          git diff-index --exit-code HEAD

jsapp/js/api.ts

@@ -118,13 +118,13 @@ export interface FetchDataOptions {
   includeHeaders?: boolean
 }
 
-const fetchData = async <T>(
+export const fetchDataRaw = async <T>(
   /**
    * If you have full url to be called, remember to use `prependRootUrl` option.
    */
   path: string,
   method: FetchHttpMethod,
-  data?: Json,
+  data?: string,
   options?: FetchDataOptions,
 ) => {
   // Prepare options
@@ -158,7 +158,7 @@ const fetchData = async <T>(
   }
 
   if (data) {
-    fetchOptions['body'] = JSON.stringify(data)
+    fetchOptions['body'] = data
   }
 
   const response = await fetch(url, fetchOptions)
@@ -210,9 +210,22 @@ const fetchData = async <T>(
     } as { headers: Headers } & T
   }
 
-  return responseJson as T
+  return { data: responseJson, status: response.status, headers: response.headers } as T
 }
 
+const fetchData = async <T>(
+  /**
+   * If you have full url to be called, remember to use `prependRootUrl` option.
+   */
+  path: string,
+  method: FetchHttpMethod,
+  data?: Json,
+  options?: FetchDataOptions,
+) => {
+  const body = data ? JSON.stringify(data) : undefined
+  const response = await fetchDataRaw<{ data: T; status: number; headers: unknown }>(path, method, body, options)
+  return response.data
+}
 /** GET Kobo API at path */
 export const fetchGet = async <T>(path: string, options?: FetchDataOptions) =>
   fetchData<T>(path, 'GET', undefined, options)

jsapp/js/api/models/_dataResponseAttachments.ts

@@ -0,0 +1,18 @@
+/**
+ * Generated by orval v7.10.0 🍺
+ * Do not edit manually.
+ * KoboToolbox API
+ * Powerful and intuitive data collection tools to make an impact
+ * OpenAPI spec version: 2.0.0 (api_v2)
+ */
+
+export type _DataResponseAttachments = {
+  download_url?: string
+  download_large_url?: string
+  download_medium_url?: string
+  download_small_url?: string
+  mimetype?: string
+  filename?: string
+  uid?: string
+  question_xpath?: string
+}

jsapp/js/api/models/_exportCreatePayloadQueryAndItemSubmissionTime.ts

@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.10.0 🍺
+ * Do not edit manually.
+ * KoboToolbox API
+ * Powerful and intuitive data collection tools to make an impact
+ * OpenAPI spec version: 2.0.0 (api_v2)
+ */
+
+export type _ExportCreatePayloadQueryAndItemSubmissionTime = {
+  $gte?: string
+}

jsapp/js/api/models/_exportSettingCreatePayloadExportSettingsQueryAndItemSubmissionTime.ts

@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.10.0 🍺
+ * Do not edit manually.
+ * KoboToolbox API
+ * Powerful and intuitive data collection tools to make an impact
+ * OpenAPI spec version: 2.0.0 (api_v2)
+ */
+
+export type _ExportSettingCreatePayloadExportSettingsQueryAndItemSubmissionTime = {
+  $gte?: string
+}

jsapp/js/api/models/_permissionAssignmentCreateRequestOneOfTwoPartialPermissionItemFilterItemSubmittedBy.ts

@@ -0,0 +1,11 @@
+/**
+ * Generated by orval v7.10.0 🍺
+ * Do not edit manually.
+ * KoboToolbox API
+ * Powerful and intuitive data collection tools to make an impact
+ * OpenAPI spec version: 2.0.0 (api_v2)
+ */
+
+export type _PermissionAssignmentCreateRequestOneOfTwoPartialPermissionItemFilterItemSubmittedBy = {
+  $in?: string[]
+}

jsapp/js/api/models/accessLogsListParams.ts

@@ -0,0 +1,19 @@
+/**
+ * Generated by orval v7.10.0 🍺
+ * Do not edit manually.
+ * KoboToolbox API
+ * Powerful and intuitive data collection tools to make an impact
+ * OpenAPI spec version: 2.0.0 (api_v2)
+ */
+
+export type AccessLogsListParams = {
+  /**
+   * Number of results to return per page.
+   */
+  limit?: number
+  /**
+   * The initial index from which to return the results.
+   */
+  offset?: number
+  q?: string
+}

jsapp/js/api/models/accessLogsMeListParams.ts

@@ -0,0 +1,19 @@
+/**
+ * Generated by orval v7.10.0 🍺
+ * Do not edit manually.
+ * KoboToolbox API
+ * Powerful and intuitive data collection tools to make an impact
+ * OpenAPI spec version: 2.0.0 (api_v2)
+ */
+
+export type AccessLogsMeListParams = {
+  /**
+   * Number of results to return per page.
+   */
+  limit?: number
+  /**
+   * The initial index from which to return the results.
+   */
+  offset?: number
+  q?: string
+}

jsapp/js/api/models/asset.ts

@@ -0,0 +1,95 @@
+import type { AssetAdvancedFeatures } from './assetAdvancedFeatures'
+import type { AssetAdvancedSubmissionSchema } from './assetAdvancedSubmissionSchema'
+import type { AssetAnalysisFormJson } from './assetAnalysisFormJson'
+import type { AssetAssignablePermissionsItem } from './assetAssignablePermissionsItem'
+import type { AssetChildren } from './assetChildren'
+import type { AssetContent } from './assetContent'
+import type { AssetDataSharing } from './assetDataSharing'
+import type { AssetDeployedVersions } from './assetDeployedVersions'
+import type { AssetDeploymentDataDownloadLinks } from './assetDeploymentDataDownloadLinks'
+import type { AssetDeploymentLinks } from './assetDeploymentLinks'
+import type { AssetDownloadsItem } from './assetDownloadsItem'
+import type { AssetEffectivePermissionsItem } from './assetEffectivePermissionsItem'
+import type { AssetEmbedsItem } from './assetEmbedsItem'
+import type { AssetExportSettings } from './assetExportSettings'
+import type { AssetMapCustom } from './assetMapCustom'
+import type { AssetMapStyles } from './assetMapStyles'
+import type { AssetProjectOwnership } from './assetProjectOwnership'
+import type { AssetReportCustom } from './assetReportCustom'
+import type { AssetReportStyles } from './assetReportStyles'
+/**
+ * Generated by orval v7.10.0 🍺
+ * Do not edit manually.
+ * KoboToolbox API
+ * Powerful and intuitive data collection tools to make an impact
+ * OpenAPI spec version: 2.0.0 (api_v2)
+ */
+import type { AssetSettings } from './assetSettings'
+import type { AssetSummary } from './assetSummary'
+import type { AssetTypeEnum } from './assetTypeEnum'
+
+export interface Asset {
+  readonly url: string
+  readonly owner: string
+  /** Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only. */
+  readonly owner__username: string
+  /** @nullable */
+  parent?: string | null
+  settings?: AssetSettings
+  asset_type: AssetTypeEnum
+  readonly files: readonly string[]
+  readonly summary: AssetSummary
+  date_created?: string
+  date_modified?: string
+  /** @nullable */
+  date_deployed?: string | null
+  readonly version_id: string
+  readonly version__content_hash: string
+  readonly version_count: number
+  readonly has_deployment: boolean
+  readonly deployed_version_id: string
+  readonly deployed_versions: AssetDeployedVersions
+  readonly deployment__links: AssetDeploymentLinks
+  readonly deployment__active: boolean
+  readonly deployment__data_download_links: AssetDeploymentDataDownloadLinks
+  readonly deployment__submission_count: number
+  readonly deployment__last_submission_time: string
+  readonly deployment__encrypted: boolean
+  readonly deployment__uuid: string
+  readonly deployment_status: string
+  report_styles?: AssetReportStyles
+  report_custom?: AssetReportCustom
+  advanced_features?: AssetAdvancedFeatures
+  readonly advanced_submission_schema: AssetAdvancedSubmissionSchema
+  readonly analysis_form_json: AssetAnalysisFormJson
+  map_styles?: AssetMapStyles
+  map_custom?: AssetMapCustom
+  content?: AssetContent
+  readonly downloads: readonly AssetDownloadsItem[]
+  readonly embeds: readonly AssetEmbedsItem[]
+  readonly xform_link: string
+  readonly hooks_link: string
+  tag_string?: string
+  readonly uid: string
+  readonly kind: string
+  readonly xls_link: string
+  /** @maxLength 255 */
+  name?: string
+  readonly assignable_permissions: readonly AssetAssignablePermissionsItem[]
+  readonly permissions: readonly string[]
+  readonly effective_permissions: readonly AssetEffectivePermissionsItem[]
+  readonly exports: string
+  readonly export_settings: readonly AssetExportSettings[]
+  readonly data: string
+  readonly children: AssetChildren
+  readonly subscribers_count: number
+  readonly status: string
+  readonly access_types: readonly string[]
+  data_sharing?: AssetDataSharing
+  readonly paired_data: string
+  /** @nullable */
+  readonly project_ownership: AssetProjectOwnership
+  readonly owner_label: string
+  /** @nullable */
+  readonly last_modified_by: string | null
+}

jsapp/js/api/models/assetAdvancedFeatures.ts

@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v7.10.0 🍺
+ * Do not edit manually.
+ * KoboToolbox API
+ * Powerful and intuitive data collection tools to make an impact
+ * OpenAPI spec version: 2.0.0 (api_v2)
+ */
+
+export type AssetAdvancedFeatures = { [key: string]: unknown }