refactor: open api

.dockerignore

@@ -8,7 +8,7 @@ machine-learning/
 misc/
 mobile/
 
-server/node_modules
+server/node_modules/
 server/coverage/
 server/.reverse-geocoding-dump/
 server/upload/
@@ -19,7 +19,10 @@ web/coverage/
 web/.svelte-kit
 web/build/
 
-cli/node_modules
+cli/node_modules/
 cli/.reverse-geocoding-dump/
 cli/upload/
-cli/dist/
+cli/dist/
+
+open-api/typescript-sdk/node_modules/
+open-api/typescript-sdk/build/

.gitattributes

@@ -8,14 +8,9 @@ mobile/openapi/.openapi-generator/FILES linguist-generated=true
 mobile/lib/**/*.g.dart -diff -merge
 mobile/lib/**/*.g.dart linguist-generated=true
 
-cli/src/api/open-api/**/*.md -diff -merge
-cli/src/api/open-api/**/*.md linguist-generated=true
-cli/src/api/open-api/**/*.ts -diff -merge
-cli/src/api/open-api/**/*.ts linguist-generated=true
-
-web/src/api/open-api/**/*.md -diff -merge
-web/src/api/open-api/**/*.md linguist-generated=true
-web/src/api/open-api/**/*.ts -diff -merge
-web/src/api/open-api/**/*.ts linguist-generated=true
+open-api/typescript-sdk/client/**/*.md -diff -merge
+open-api/typescript-sdk/client/**/*.md linguist-generated=true
+open-api/typescript-sdk/client/**/*.ts -diff -merge
+open-api/typescript-sdk/client/**/*.ts linguist-generated=true
 
 *.sh text eol=lf

.github/workflows/test.yml

@@ -107,10 +107,18 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Run npm install in cli
+      - name: Run npm install (typescript-sdk)
         run: npm ci
+        working-directory: ./open-api/typescript-sdk
 
-      - name: Run npm install in server
+      - name: Run build (typescript-sdk)
+        run: npm run build
+        working-directory: ./open-api/typescript-sdk
+
+      - name: Run npm install (cli)
+        run: npm ci
+
+      - name: Run npm install (server)
         run: npm ci
         working-directory: ./server
 
@@ -143,10 +151,18 @@ jobs:
         with:
           submodules: "recursive"
 
-      - name: Run npm install in cli
+      - name: Run npm install (typescript-sdk)
+        run: npm ci
+        working-directory: ./open-api/typescript-sdk
+
+      - name: Run build (typescript-sdk)
+        run: npm run build
+        working-directory: ./open-api/typescript-sdk
+
+      - name: Run npm install (cli)
         run: npm ci
 
-      - name: Run npm install in server
+      - name: Run npm install (server)
         run: npm ci
         working-directory: ./server
 
@@ -237,14 +253,14 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Run API generation
-        run: npm --prefix server run api:generate
+        run: make open-api
       - name: Find file changes
         uses: tj-actions/verify-changed-files@v13.1
         id: verify-changed-files
         with:
           files: |
             mobile/openapi
-            web/src/api/open-api
+            open-api/typescript-sdk
       - name: Verify files have not changed
         if: steps.verify-changed-files.outputs.files_changed == 'true'
         run: |

.gitignore

@@ -1,3 +1,5 @@
+**/node_modules/**
+
 .DS_Store
 .vscode/*
 !.vscode/launch.json
@@ -12,3 +14,5 @@ mobile/gradle.properties
 mobile/openapi/pubspec.lock
 mobile/*.jks
 mobile/libisar.dylib
+
+open-api/typescript-sdk/build

Makefile

@@ -25,8 +25,15 @@ prod:
 prod-scale:
 	docker compose -f ./docker/docker-compose.prod.yml up --build -V --scale immich-server=3 --scale immich-microservices=3 --remove-orphans
 
-api:
-	npm --prefix server run api:generate
+.PHONY: open-api
+open-api:
+	cd ./open-api && bash ./bin/generate-open-api.sh
+
+open-api-dart:
+	cd ./open-api && bash ./bin/generate-open-api.sh dart
+
+open-api-typescript:
+	cd ./open-api && bash ./bin/generate-open-api.sh typescript
 
 sql:
 	npm --prefix server run sql:generate

cli/.prettierignore

@@ -5,7 +5,6 @@ node_modules
 .env
 .env.*
 !.env.example
-src/api/open-api
 *.md
 *.json
 coverage

cli/package.json

@@ -12,6 +12,7 @@
     "cli"
   ],
   "dependencies": {
+    "@immich/sdk": "file:../open-api/typescript-sdk",
     "axios": "^1.6.2",
     "byte-size": "^8.1.1",
     "cli-progress": "^3.12.0",

cli/src/api/client.ts

@@ -9,7 +9,7 @@ import {
   ServerInfoApi,
   SystemConfigApi,
   UserApi,
-} from './open-api';
+} from '@immich/sdk';
 import { ApiConfiguration } from '../cores/api-configuration';
 import FormData from 'form-data';
 

cli/src/cli/base-command.ts

@@ -2,7 +2,7 @@ import { ImmichApi } from '../api/client';
 import { SessionService } from '../services/session.service';
 import { LoginError } from '../cores/errors/login-error';
 import { exit } from 'node:process';
-import { ServerVersionResponseDto, UserResponseDto } from 'src/api/open-api';
+import { ServerVersionResponseDto, UserResponseDto } from '@immich/sdk';
 import { BaseOptionsDto } from 'src/cores/dto/base-options-dto';
 
 export abstract class BaseCommand {

cli/src/commands/upload.ts

@@ -6,7 +6,7 @@ import fs from 'node:fs';
 import cliProgress from 'cli-progress';
 import byteSize from 'byte-size';
 import { BaseCommand } from '../cli/base-command';
-import axios, { AxiosRequestConfig } from 'axios';
+import axios, { AxiosRequestConfig, AxiosResponse } from 'axios';
 import FormData from 'form-data';
 
 export default class Upload extends BaseCommand {
@@ -172,7 +172,7 @@ export default class Upload extends BaseCommand {
     }
   }
 
-  private async uploadAsset(data: FormData): Promise<axios.AxiosResponse> {
+  private async uploadAsset(data: FormData): Promise<AxiosResponse> {
     const url = this.immichApi.apiConfiguration.instanceUrl + '/asset/upload';
 
     const config: AxiosRequestConfig = {

cli/src/services/session.service.spec.ts

@@ -16,10 +16,9 @@ import {
 const mockPingServer = jest.fn(() => Promise.resolve({ data: { res: 'pong' } }));
 const mockUserInfo = jest.fn(() => Promise.resolve({ data: { email: 'admin@example.com' } }));
 
-jest.mock('../api/open-api', () => {
+jest.mock('@immich/sdk', () => {
   return {
-    __esModule: true,
-    ...jest.requireActual('../api/open-api'),
+    ...jest.requireActual('@immich/sdk'),
     UserApi: jest.fn().mockImplementation(() => {
       return { getMyUserInfo: mockUserInfo };
     }),

cli/test/e2e/login-key.e2e-spec.ts

@@ -1,7 +1,7 @@
 import { APIKeyCreateResponseDto } from '@app/domain';
 import { api } from '@test/../e2e/api/client';
 import { restoreTempFolder, testApp } from '@test/../e2e/jobs/utils';
-import { LoginResponseDto } from 'src/api/open-api';
+import { LoginResponseDto } from '@immich/sdk';
 import LoginKey from 'src/commands/login/key';
 import { LoginError } from 'src/cores/errors/login-error';
 import { CLI_BASE_OPTIONS, spyOnConsole } from 'test/cli-test-utils';

cli/test/e2e/server-info.e2e-spec.ts

@@ -1,7 +1,7 @@
 import { APIKeyCreateResponseDto } from '@app/domain';
 import { api } from '@test/../e2e/api/client';
 import { restoreTempFolder, testApp } from '@test/../e2e/jobs/utils';
-import { LoginResponseDto } from 'src/api/open-api';
+import { LoginResponseDto } from '@immich/sdk';
 import ServerInfo from 'src/commands/server-info';
 import { CLI_BASE_OPTIONS, spyOnConsole } from 'test/cli-test-utils';
 

cli/test/e2e/upload.e2e-spec.ts

@@ -1,7 +1,7 @@
 import { APIKeyCreateResponseDto } from '@app/domain';
 import { api } from '@test/../e2e/api/client';
 import { IMMICH_TEST_ASSET_PATH, restoreTempFolder, testApp } from '@test/../e2e/jobs/utils';
-import { LoginResponseDto } from 'src/api/open-api';
+import { LoginResponseDto } from '@immich/sdk';
 import Upload from 'src/commands/upload';
 import { CLI_BASE_OPTIONS, spyOnConsole } from 'test/cli-test-utils';
 

cli/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "compilerOptions": {
-    "module": "Node16",
+    "module": "commonjs",
     "strict": true,
     "declaration": true,
     "removeComments": true,
@@ -9,7 +9,6 @@
     "allowSyntheticDefaultImports": true,
     "resolveJsonModule": true,
     "target": "es2021",
-    "moduleResolution": "node16",
     "sourceMap": true,
     "outDir": "./dist",
     "incremental": true,

docker/docker-compose.dev.yml

@@ -15,6 +15,7 @@ x-server-build: &server-common
   restart: always
   volumes:
     - ../server:/usr/src/app
+    - ../open-api:/usr/src/open-api
     - ${UPLOAD_LOCATION}/photos:/usr/src/app/upload
     - ${UPLOAD_LOCATION}/photos/upload:/usr/src/app/upload/upload
     - /usr/src/app/node_modules
@@ -65,6 +66,7 @@ services:
       - 24678:24678
     volumes:
       - ../web:/usr/src/app
+      - ../open-api/:/usr/src/open-api/
       - /usr/src/app/node_modules
     ulimits:
       nofile:

docs/docs/developer/open-api.md

@@ -13,5 +13,5 @@ npm run api:generate # Run from the `server/` directory
 You can find the generated client SDK in the `web/src/api` for Typescript SDK and `mobile/openapi` for Dart SDK.
 
 :::tip
-This can also be run via `make api` from the project root directory (not in the `server` folder)
+This can also be run via `make open-api` from the project root directory (not in the `server` folder)
 :::

docs/docusaurus.config.js

@@ -56,7 +56,7 @@ const config = {
           editUrl: 'https://github.com/immich-app/immich/tree/main/docs/',
         },
         api: {
-          path: '../server/immich-openapi-specs.json',
+          path: '../open-api/immich-openapi-specs.json',
           routeBasePath: '/docs/api',
         },
         // blog: {

open-api/bin/generate-open-api.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+OPENAPI_GENEARTOR_VERSION=v6.6.0
+
+# usage: ./bin/generate-open-api.sh
+
+function dart {
+  rm -rf ../mobile/openapi
+  cd ./templates/mobile/serialization/native
+  wget -O native_class.mustache https://raw.githubusercontent.com/OpenAPITools/openapi-generator/$OPENAPI_GENEARTOR_VERSION/modules/openapi-generator/src/main/resources/dart2/serialization/native/native_class.mustache
+  patch -u native_class.mustache <native_class.mustache.patch
+  cd ../../../..
+  npx --yes @openapitools/openapi-generator-cli generate -g dart -i ./immich-openapi-specs.json -o ../mobile/openapi -t ./templates/mobile
+
+  # Post generate patches
+  patch --no-backup-if-mismatch -u ../mobile/openapi/lib/api_client.dart <./patch/api_client.dart.patch
+  patch --no-backup-if-mismatch -u ../mobile/openapi/lib/api.dart <./patch/api.dart.patch
+  sed -i 's/0.17.0/0.18.0/g' ../mobile/openapi/pubspec.yaml
+}
+
+function typescript {
+  rm -rf ./typescript-sdk/client
+  cd ./templates/typescript
+  wget -O apiInner.mustache https://raw.githubusercontent.com/OpenAPITools/openapi-generator/$OPENAPI_GENEARTOR_VERSION/modules/openapi-generator/src/main/resources/typescript-axios/apiInner.mustache
+  patch -u apiInner.mustache < apiInner.mustache.patch
+  cd ../..
+  npx --yes @openapitools/openapi-generator-cli generate -g typescript-axios -i ./immich-openapi-specs.json -o ./typescript-sdk/client -t ./templates/typescript --additional-properties=useSingleRequestParameter=true
+}
+
+node ./bin/sync-spec-version.js
+
+if [[ $1 == 'dart' ]]; then
+  dart
+elif [[ $1 == 'typescript' ]]; then
+  typescript
+else
+  dart
+  typescript
+fi

open-api/bin/sync-spec-version.js

@@ -0,0 +1,9 @@
+const spec = require('../immich-openapi-specs.json');
+const pkg = require('../../server/package.json');
+const path = require('path');
+const fs = require('fs');
+spec.info.version = pkg.version;
+fs.writeFileSync(
+  path.join(__dirname, '../immich-openapi-specs.json'),
+  JSON.stringify(spec, null, 2)
+);