diff --git a/mobile/openapi/lib/api/assets_api.dart b/mobile/openapi/lib/api/assets_api.dart index fdb171bedc..5020afc4b2 100644 --- a/mobile/openapi/lib/api/assets_api.dart +++ b/mobile/openapi/lib/api/assets_api.dart @@ -352,7 +352,7 @@ class AssetsApi { /// Retrieve assets by device ID /// - /// This property was deprecated in v2.0.0. Get all asset of a device that are in the database, ID only. + /// Get all asset of a device that are in the database, ID only. /// /// Note: This method returns the HTTP [Response]. /// @@ -387,7 +387,7 @@ class AssetsApi { /// Retrieve assets by device ID /// - /// This property was deprecated in v2.0.0. Get all asset of a device that are in the database, ID only. + /// Get all asset of a device that are in the database, ID only. /// /// Parameters: /// @@ -740,7 +740,7 @@ class AssetsApi { /// Get random assets /// - /// This property was deprecated in v1.116.0. Retrieve a specified number of random assets for the authenticated user. + /// Retrieve a specified number of random assets for the authenticated user. /// /// Note: This method returns the HTTP [Response]. /// @@ -778,7 +778,7 @@ class AssetsApi { /// Get random assets /// - /// This property was deprecated in v1.116.0. Retrieve a specified number of random assets for the authenticated user. + /// Retrieve a specified number of random assets for the authenticated user. /// /// Parameters: /// @@ -875,7 +875,7 @@ class AssetsApi { /// Replace asset /// - /// This property was deprecated in v1.142.0. Replace the asset with new file, without changing its id. + /// Replace the asset with new file, without changing its id. /// /// Note: This method returns the HTTP [Response]. /// @@ -969,7 +969,7 @@ class AssetsApi { /// Replace asset /// - /// This property was deprecated in v1.142.0. Replace the asset with new file, without changing its id. + /// Replace the asset with new file, without changing its id. /// /// Parameters: /// diff --git a/mobile/openapi/lib/api/deprecated_api.dart b/mobile/openapi/lib/api/deprecated_api.dart index b47b26b148..aaf7c074b9 100644 --- a/mobile/openapi/lib/api/deprecated_api.dart +++ b/mobile/openapi/lib/api/deprecated_api.dart @@ -18,7 +18,7 @@ class DeprecatedApi { /// Create a partner /// - /// This property was deprecated in v1.141.0. Create a new partner to share assets with. + /// Create a new partner to share assets with. /// /// Note: This method returns the HTTP [Response]. /// @@ -53,7 +53,7 @@ class DeprecatedApi { /// Create a partner /// - /// This property was deprecated in v1.141.0. Create a new partner to share assets with. + /// Create a new partner to share assets with. /// /// Parameters: /// @@ -75,7 +75,7 @@ class DeprecatedApi { /// Retrieve assets by device ID /// - /// This property was deprecated in v2.0.0. Get all asset of a device that are in the database, ID only. + /// Get all asset of a device that are in the database, ID only. /// /// Note: This method returns the HTTP [Response]. /// @@ -110,7 +110,7 @@ class DeprecatedApi { /// Retrieve assets by device ID /// - /// This property was deprecated in v2.0.0. Get all asset of a device that are in the database, ID only. + /// Get all asset of a device that are in the database, ID only. /// /// Parameters: /// @@ -135,7 +135,7 @@ class DeprecatedApi { /// Get delta sync for user /// - /// This property was deprecated in v2.0.0. Retrieve changed assets since the last sync for the authenticated user. + /// Retrieve changed assets since the last sync for the authenticated user. /// /// Note: This method returns the HTTP [Response]. /// @@ -169,7 +169,7 @@ class DeprecatedApi { /// Get delta sync for user /// - /// This property was deprecated in v2.0.0. Retrieve changed assets since the last sync for the authenticated user. + /// Retrieve changed assets since the last sync for the authenticated user. /// /// Parameters: /// @@ -191,7 +191,7 @@ class DeprecatedApi { /// Get full sync for user /// - /// This property was deprecated in v2.0.0. Retrieve all assets for a full synchronization for the authenticated user. + /// Retrieve all assets for a full synchronization for the authenticated user. /// /// Note: This method returns the HTTP [Response]. /// @@ -225,7 +225,7 @@ class DeprecatedApi { /// Get full sync for user /// - /// This property was deprecated in v2.0.0. Retrieve all assets for a full synchronization for the authenticated user. + /// Retrieve all assets for a full synchronization for the authenticated user. /// /// Parameters: /// @@ -250,7 +250,7 @@ class DeprecatedApi { /// Get random assets /// - /// This property was deprecated in v1.116.0. Retrieve a specified number of random assets for the authenticated user. + /// Retrieve a specified number of random assets for the authenticated user. /// /// Note: This method returns the HTTP [Response]. /// @@ -288,7 +288,7 @@ class DeprecatedApi { /// Get random assets /// - /// This property was deprecated in v1.116.0. Retrieve a specified number of random assets for the authenticated user. + /// Retrieve a specified number of random assets for the authenticated user. /// /// Parameters: /// @@ -313,7 +313,7 @@ class DeprecatedApi { /// Replace asset /// - /// This property was deprecated in v1.142.0. Replace the asset with new file, without changing its id. + /// Replace the asset with new file, without changing its id. /// /// Note: This method returns the HTTP [Response]. /// @@ -407,7 +407,7 @@ class DeprecatedApi { /// Replace asset /// - /// This property was deprecated in v1.142.0. Replace the asset with new file, without changing its id. + /// Replace the asset with new file, without changing its id. /// /// Parameters: /// diff --git a/mobile/openapi/lib/api/partners_api.dart b/mobile/openapi/lib/api/partners_api.dart index 9cbd4bfedb..7d18f6d867 100644 --- a/mobile/openapi/lib/api/partners_api.dart +++ b/mobile/openapi/lib/api/partners_api.dart @@ -74,7 +74,7 @@ class PartnersApi { /// Create a partner /// - /// This property was deprecated in v1.141.0. Create a new partner to share assets with. + /// Create a new partner to share assets with. /// /// Note: This method returns the HTTP [Response]. /// @@ -109,7 +109,7 @@ class PartnersApi { /// Create a partner /// - /// This property was deprecated in v1.141.0. Create a new partner to share assets with. + /// Create a new partner to share assets with. /// /// Parameters: /// diff --git a/mobile/openapi/lib/api/search_api.dart b/mobile/openapi/lib/api/search_api.dart index 375e9a1e87..ee5f64753c 100644 --- a/mobile/openapi/lib/api/search_api.dart +++ b/mobile/openapi/lib/api/search_api.dart @@ -131,7 +131,6 @@ class SearchApi { /// * [String] country: /// /// * [bool] includeNull: - /// This property was added in v111.0.0 /// /// * [String] lensModel: /// @@ -196,7 +195,6 @@ class SearchApi { /// * [String] country: /// /// * [bool] includeNull: - /// This property was added in v111.0.0 /// /// * [String] lensModel: /// diff --git a/mobile/openapi/lib/api/sync_api.dart b/mobile/openapi/lib/api/sync_api.dart index b1a3e61455..6194fd0f89 100644 --- a/mobile/openapi/lib/api/sync_api.dart +++ b/mobile/openapi/lib/api/sync_api.dart @@ -66,7 +66,7 @@ class SyncApi { /// Get delta sync for user /// - /// This property was deprecated in v2.0.0. Retrieve changed assets since the last sync for the authenticated user. + /// Retrieve changed assets since the last sync for the authenticated user. /// /// Note: This method returns the HTTP [Response]. /// @@ -100,7 +100,7 @@ class SyncApi { /// Get delta sync for user /// - /// This property was deprecated in v2.0.0. Retrieve changed assets since the last sync for the authenticated user. + /// Retrieve changed assets since the last sync for the authenticated user. /// /// Parameters: /// @@ -122,7 +122,7 @@ class SyncApi { /// Get full sync for user /// - /// This property was deprecated in v2.0.0. Retrieve all assets for a full synchronization for the authenticated user. + /// Retrieve all assets for a full synchronization for the authenticated user. /// /// Note: This method returns the HTTP [Response]. /// @@ -156,7 +156,7 @@ class SyncApi { /// Get full sync for user /// - /// This property was deprecated in v2.0.0. Retrieve all assets for a full synchronization for the authenticated user. + /// Retrieve all assets for a full synchronization for the authenticated user. /// /// Parameters: /// diff --git a/mobile/openapi/lib/model/asset_response_dto.dart b/mobile/openapi/lib/model/asset_response_dto.dart index dc957b3bfc..8d49986359 100644 --- a/mobile/openapi/lib/model/asset_response_dto.dart +++ b/mobile/openapi/lib/model/asset_response_dto.dart @@ -87,7 +87,6 @@ class AssetResponseDto { bool isTrashed; - /// This property was deprecated in v1.106.0 String? libraryId; String? livePhotoVideoId; @@ -119,7 +118,6 @@ class AssetResponseDto { List people; - /// This property was deprecated in v1.113.0 /// /// Please note: This property should have been non-nullable! Since the specification file /// does not include a default value (using the "default:" property), however, the generated diff --git a/mobile/openapi/lib/model/people_response_dto.dart b/mobile/openapi/lib/model/people_response_dto.dart index 49f0e85aad..901c38ade9 100644 --- a/mobile/openapi/lib/model/people_response_dto.dart +++ b/mobile/openapi/lib/model/people_response_dto.dart @@ -19,7 +19,6 @@ class PeopleResponseDto { required this.total, }); - /// This property was added in v1.110.0 /// /// Please note: This property should have been non-nullable! Since the specification file /// does not include a default value (using the "default:" property), however, the generated diff --git a/mobile/openapi/lib/model/person_response_dto.dart b/mobile/openapi/lib/model/person_response_dto.dart index c9ebb14c72..a6ad5e0c24 100644 --- a/mobile/openapi/lib/model/person_response_dto.dart +++ b/mobile/openapi/lib/model/person_response_dto.dart @@ -25,7 +25,6 @@ class PersonResponseDto { DateTime? birthDate; - /// This property was added in v1.126.0 /// /// Please note: This property should have been non-nullable! Since the specification file /// does not include a default value (using the "default:" property), however, the generated @@ -36,7 +35,6 @@ class PersonResponseDto { String id; - /// This property was added in v1.126.0 /// /// Please note: This property should have been non-nullable! Since the specification file /// does not include a default value (using the "default:" property), however, the generated @@ -51,7 +49,6 @@ class PersonResponseDto { String thumbnailPath; - /// This property was added in v1.107.0 /// /// Please note: This property should have been non-nullable! Since the specification file /// does not include a default value (using the "default:" property), however, the generated diff --git a/mobile/openapi/lib/model/person_with_faces_response_dto.dart b/mobile/openapi/lib/model/person_with_faces_response_dto.dart index 0bd38b0870..9b2e40cf56 100644 --- a/mobile/openapi/lib/model/person_with_faces_response_dto.dart +++ b/mobile/openapi/lib/model/person_with_faces_response_dto.dart @@ -26,7 +26,6 @@ class PersonWithFacesResponseDto { DateTime? birthDate; - /// This property was added in v1.126.0 /// /// Please note: This property should have been non-nullable! Since the specification file /// does not include a default value (using the "default:" property), however, the generated @@ -39,7 +38,6 @@ class PersonWithFacesResponseDto { String id; - /// This property was added in v1.126.0 /// /// Please note: This property should have been non-nullable! Since the specification file /// does not include a default value (using the "default:" property), however, the generated @@ -54,7 +52,6 @@ class PersonWithFacesResponseDto { String thumbnailPath; - /// This property was added in v1.107.0 /// /// Please note: This property should have been non-nullable! Since the specification file /// does not include a default value (using the "default:" property), however, the generated diff --git a/open-api/immich-openapi-specs.json b/open-api/immich-openapi-specs.json index c6dc9061e9..e4fc5ddd96 100644 --- a/open-api/immich-openapi-specs.json +++ b/open-api/immich-openapi-specs.json @@ -80,7 +80,22 @@ "tags": [ "Activities" ], - "x-immich-permission": "activity.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "activity.read", + "x-immich-state": "Stable" }, "post": { "description": "Create a like or a comment for an album, or an asset in an album.", @@ -123,7 +138,22 @@ "tags": [ "Activities" ], - "x-immich-permission": "activity.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "activity.create", + "x-immich-state": "Stable" } }, "/activities/statistics": { @@ -177,7 +207,22 @@ "tags": [ "Activities" ], - "x-immich-permission": "activity.statistics" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "activity.statistics", + "x-immich-state": "Stable" } }, "/activities/{id}": { @@ -215,7 +260,22 @@ "tags": [ "Activities" ], - "x-immich-permission": "activity.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "activity.delete", + "x-immich-state": "Stable" } }, "/admin/auth/unlink-all": { @@ -244,7 +304,22 @@ "Authentication (admin)" ], "x-immich-admin-only": true, - "x-immich-permission": "adminAuth.unlinkAll" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "adminAuth.unlinkAll", + "x-immich-state": "Stable" } }, "/admin/notifications": { @@ -289,7 +364,22 @@ "tags": [ "Notifications (admin)" ], - "x-immich-admin-only": true + "x-immich-admin-only": true, + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/admin/notifications/templates/{name}": { @@ -343,7 +433,22 @@ "tags": [ "Notifications (admin)" ], - "x-immich-admin-only": true + "x-immich-admin-only": true, + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/admin/notifications/test-email": { @@ -388,7 +493,22 @@ "tags": [ "Notifications (admin)" ], - "x-immich-admin-only": true + "x-immich-admin-only": true, + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/admin/users": { @@ -445,7 +565,22 @@ "Users (admin)" ], "x-immich-admin-only": true, - "x-immich-permission": "adminUser.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "adminUser.read", + "x-immich-state": "Stable" }, "post": { "description": "Create a new user.", @@ -489,7 +624,22 @@ "Users (admin)" ], "x-immich-admin-only": true, - "x-immich-permission": "adminUser.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "adminUser.create", + "x-immich-state": "Stable" } }, "/admin/users/{id}": { @@ -545,7 +695,22 @@ "Users (admin)" ], "x-immich-admin-only": true, - "x-immich-permission": "adminUser.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "adminUser.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve a specific user by their ID.", @@ -589,7 +754,22 @@ "Users (admin)" ], "x-immich-admin-only": true, - "x-immich-permission": "adminUser.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "adminUser.read", + "x-immich-state": "Stable" }, "put": { "description": "Update an existing user.", @@ -643,7 +823,22 @@ "Users (admin)" ], "x-immich-admin-only": true, - "x-immich-permission": "adminUser.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "adminUser.update", + "x-immich-state": "Stable" } }, "/admin/users/{id}/preferences": { @@ -689,7 +884,22 @@ "Users (admin)" ], "x-immich-admin-only": true, - "x-immich-permission": "adminUser.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "adminUser.read", + "x-immich-state": "Stable" }, "put": { "description": "Update the preferences of a specific user.", @@ -743,7 +953,22 @@ "Users (admin)" ], "x-immich-admin-only": true, - "x-immich-permission": "adminUser.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "adminUser.update", + "x-immich-state": "Stable" } }, "/admin/users/{id}/restore": { @@ -789,7 +1014,22 @@ "Users (admin)" ], "x-immich-admin-only": true, - "x-immich-permission": "adminUser.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "adminUser.delete", + "x-immich-state": "Stable" } }, "/admin/users/{id}/sessions": { @@ -838,7 +1078,22 @@ "Users (admin)" ], "x-immich-admin-only": true, - "x-immich-permission": "adminSession.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "adminSession.read", + "x-immich-state": "Stable" } }, "/admin/users/{id}/statistics": { @@ -908,7 +1163,22 @@ "Users (admin)" ], "x-immich-admin-only": true, - "x-immich-permission": "adminUser.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "adminUser.read", + "x-immich-state": "Stable" } }, "/albums": { @@ -965,7 +1235,22 @@ "tags": [ "Albums" ], - "x-immich-permission": "album.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "album.read", + "x-immich-state": "Stable" }, "post": { "description": "Create a new album. The album can also be created with initial users and assets.", @@ -1008,7 +1293,22 @@ "tags": [ "Albums" ], - "x-immich-permission": "album.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "album.create", + "x-immich-state": "Stable" } }, "/albums/assets": { @@ -1070,7 +1370,22 @@ "tags": [ "Albums" ], - "x-immich-permission": "albumAsset.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "albumAsset.create", + "x-immich-state": "Stable" } }, "/albums/statistics": { @@ -1105,7 +1420,22 @@ "tags": [ "Albums" ], - "x-immich-permission": "album.statistics" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "album.statistics", + "x-immich-state": "Stable" } }, "/albums/{id}": { @@ -1143,7 +1473,22 @@ "tags": [ "Albums" ], - "x-immich-permission": "album.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "album.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve information about a specific album by its ID.", @@ -1210,7 +1555,22 @@ "tags": [ "Albums" ], - "x-immich-permission": "album.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "album.read", + "x-immich-state": "Stable" }, "patch": { "description": "Update the information of a specific album by its ID. This endpoint can be used to update the album name, description, sort order, etc. However, it is not used to add or remove assets or users from the album.", @@ -1263,7 +1623,22 @@ "tags": [ "Albums" ], - "x-immich-permission": "album.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "album.update", + "x-immich-state": "Stable" } }, "/albums/{id}/assets": { @@ -1321,7 +1696,22 @@ "tags": [ "Albums" ], - "x-immich-permission": "albumAsset.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "albumAsset.delete", + "x-immich-state": "Stable" }, "put": { "description": "Add multiple assets to a specific album by its ID.", @@ -1393,7 +1783,22 @@ "tags": [ "Albums" ], - "x-immich-permission": "albumAsset.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "albumAsset.create", + "x-immich-state": "Stable" } }, "/albums/{id}/user/{userId}": { @@ -1439,7 +1844,22 @@ "tags": [ "Albums" ], - "x-immich-permission": "albumUser.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "albumUser.delete", + "x-immich-state": "Stable" }, "put": { "description": "Change the role for a specific user in a specific album.", @@ -1493,7 +1913,22 @@ "tags": [ "Albums" ], - "x-immich-permission": "albumUser.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "albumUser.update", + "x-immich-state": "Stable" } }, "/albums/{id}/users": { @@ -1548,7 +1983,22 @@ "tags": [ "Albums" ], - "x-immich-permission": "albumUser.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "albumUser.create", + "x-immich-state": "Stable" } }, "/api-keys": { @@ -1586,7 +2036,22 @@ "tags": [ "API keys" ], - "x-immich-permission": "apiKey.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "apiKey.read", + "x-immich-state": "Stable" }, "post": { "description": "Creates a new API key. It will be limited to the permissions specified.", @@ -1629,7 +2094,22 @@ "tags": [ "API keys" ], - "x-immich-permission": "apiKey.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "apiKey.create", + "x-immich-state": "Stable" } }, "/api-keys/me": { @@ -1663,7 +2143,22 @@ "summary": "Retrieve the current API key", "tags": [ "API keys" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/api-keys/{id}": { @@ -1701,7 +2196,22 @@ "tags": [ "API keys" ], - "x-immich-permission": "apiKey.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "apiKey.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve an API key by its ID. The current user must own this API key.", @@ -1744,7 +2254,22 @@ "tags": [ "API keys" ], - "x-immich-permission": "apiKey.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "apiKey.read", + "x-immich-state": "Stable" }, "put": { "description": "Updates the name and permissions of an API key by its ID. The current user must own this API key.", @@ -1797,7 +2322,22 @@ "tags": [ "API keys" ], - "x-immich-permission": "apiKey.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "apiKey.update", + "x-immich-state": "Stable" } }, "/assets": { @@ -1835,7 +2375,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.delete", + "x-immich-state": "Stable" }, "post": { "description": "Uploads a new asset to the server.", @@ -1905,7 +2460,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.upload" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.upload", + "x-immich-state": "Stable" }, "put": { "description": "Updates multiple assets at the same time.", @@ -1941,7 +2511,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.update", + "x-immich-state": "Stable" } }, "/assets/bulk-upload-check": { @@ -1986,7 +2571,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.upload" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.upload", + "x-immich-state": "Stable" } }, "/assets/copy": { @@ -2024,13 +2624,28 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.copy" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.copy", + "x-immich-state": "Stable" } }, "/assets/device/{deviceId}": { "get": { "deprecated": true, - "description": "This property was deprecated in v2.0.0. Get all asset of a device that are in the database, ID only.", + "description": "Get all asset of a device that are in the database, ID only.", "operationId": "getAllUserAssetsByDeviceId", "parameters": [ { @@ -2073,9 +2688,17 @@ "Assets", "Deprecated" ], - "x-immich-lifecycle": { - "deprecatedAt": "v2.0.0" - } + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v2", + "state": "Deprecated" + } + ], + "x-immich-state": "Deprecated" } }, "/assets/exist": { @@ -2119,7 +2742,22 @@ "summary": "Check existing assets", "tags": [ "Assets" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/assets/jobs": { @@ -2156,13 +2794,28 @@ "summary": "Run an asset job", "tags": [ "Assets" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/assets/random": { "get": { "deprecated": true, - "description": "This property was deprecated in v1.116.0. Retrieve a specified number of random assets for the authenticated user.", + "description": "Retrieve a specified number of random assets for the authenticated user.", "operationId": "getRandom", "parameters": [ { @@ -2206,10 +2859,19 @@ "Assets", "Deprecated" ], - "x-immich-lifecycle": { - "deprecatedAt": "v1.116.0" - }, - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Deprecated", + "replacementId": "searchAssets" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Deprecated" } }, "/assets/statistics": { @@ -2269,7 +2931,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.statistics" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.statistics", + "x-immich-state": "Stable" } }, "/assets/{id}": { @@ -2330,7 +3007,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Stable" }, "put": { "description": "Update information of a specific asset.", @@ -2383,7 +3075,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.update", + "x-immich-state": "Stable" } }, "/assets/{id}/metadata": { @@ -2431,7 +3138,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Stable" }, "put": { "description": "Update or add metadata key-value pairs for the specified asset.", @@ -2487,7 +3209,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.update", + "x-immich-state": "Stable" } }, "/assets/{id}/metadata/{key}": { @@ -2533,7 +3270,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.update", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve the value of a specific metadata key associated with the specified asset.", @@ -2584,7 +3336,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Stable" } }, "/assets/{id}/ocr": { @@ -2632,7 +3399,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Stable" } }, "/assets/{id}/original": { @@ -2694,11 +3476,26 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.download" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.download", + "x-immich-state": "Stable" }, "put": { "deprecated": true, - "description": "This property was deprecated in v1.142.0. Replace the asset with new file, without changing its id.", + "description": "Replace the asset with new file, without changing its id.", "operationId": "replaceAsset", "parameters": [ { @@ -2765,11 +3562,19 @@ "Assets", "Deprecated" ], - "x-immich-lifecycle": { - "addedAt": "v1.106.0", - "deprecatedAt": "v1.142.0" - }, - "x-immich-permission": "asset.replace" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Deprecated", + "replacementId": "copyAsset" + } + ], + "x-immich-permission": "asset.replace", + "x-immich-state": "Deprecated" } }, "/assets/{id}/thumbnail": { @@ -2839,7 +3644,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.view" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.view", + "x-immich-state": "Stable" } }, "/assets/{id}/video/playback": { @@ -2901,7 +3721,22 @@ "tags": [ "Assets" ], - "x-immich-permission": "asset.view" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.view", + "x-immich-state": "Stable" } }, "/auth/admin-sign-up": { @@ -2934,7 +3769,22 @@ "summary": "Register admin", "tags": [ "Authentication" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/auth/change-password": { @@ -2979,7 +3829,22 @@ "tags": [ "Authentication" ], - "x-immich-permission": "auth.changePassword" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "auth.changePassword", + "x-immich-state": "Stable" } }, "/auth/login": { @@ -3012,7 +3877,22 @@ "summary": "Login", "tags": [ "Authentication" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/auth/logout": { @@ -3046,7 +3926,22 @@ "summary": "Logout", "tags": [ "Authentication" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/auth/pin-code": { @@ -3084,7 +3979,22 @@ "tags": [ "Authentication" ], - "x-immich-permission": "pinCode.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "pinCode.delete", + "x-immich-state": "Stable" }, "post": { "description": "Setup a new pin code for the current user.", @@ -3120,7 +4030,22 @@ "tags": [ "Authentication" ], - "x-immich-permission": "pinCode.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "pinCode.create", + "x-immich-state": "Stable" }, "put": { "description": "Change the pin code for the current user.", @@ -3156,7 +4081,22 @@ "tags": [ "Authentication" ], - "x-immich-permission": "pinCode.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "pinCode.update", + "x-immich-state": "Stable" } }, "/auth/session/lock": { @@ -3183,7 +4123,22 @@ "summary": "Lock auth session", "tags": [ "Authentication" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/auth/session/unlock": { @@ -3220,7 +4175,22 @@ "summary": "Unlock auth session", "tags": [ "Authentication" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/auth/status": { @@ -3288,7 +4258,22 @@ "summary": "Validate access token", "tags": [ "Authentication" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/download/archive": { @@ -3351,7 +4336,22 @@ "tags": [ "Download" ], - "x-immich-permission": "asset.download" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.download", + "x-immich-state": "Stable" } }, "/download/info": { @@ -3413,7 +4413,22 @@ "tags": [ "Download" ], - "x-immich-permission": "asset.download" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.download", + "x-immich-state": "Stable" } }, "/duplicates": { @@ -3451,7 +4466,22 @@ "tags": [ "Duplicates" ], - "x-immich-permission": "duplicate.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "duplicate.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve a list of duplicate assets available to the authenticated user.", @@ -3487,7 +4517,22 @@ "tags": [ "Duplicates" ], - "x-immich-permission": "duplicate.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "duplicate.read", + "x-immich-state": "Stable" } }, "/duplicates/{id}": { @@ -3525,7 +4570,22 @@ "tags": [ "Duplicates" ], - "x-immich-permission": "duplicate.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "duplicate.delete", + "x-immich-state": "Stable" } }, "/faces": { @@ -3573,7 +4633,22 @@ "tags": [ "Faces" ], - "x-immich-permission": "face.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "face.read", + "x-immich-state": "Stable" }, "post": { "description": "Create a new face that has not been discovered by facial recognition. The content of the bounding box is considered a face.", @@ -3609,7 +4684,22 @@ "tags": [ "Faces" ], - "x-immich-permission": "face.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "face.create", + "x-immich-state": "Stable" } }, "/faces/{id}": { @@ -3657,7 +4747,22 @@ "tags": [ "Faces" ], - "x-immich-permission": "face.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "face.delete", + "x-immich-state": "Stable" }, "put": { "description": "Re-assign the face provided in the body to the person identified by the id in the path parameter.", @@ -3710,7 +4815,22 @@ "tags": [ "Faces" ], - "x-immich-permission": "face.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "face.update", + "x-immich-state": "Stable" } }, "/jobs": { @@ -3746,7 +4866,22 @@ "Jobs" ], "x-immich-admin-only": true, - "x-immich-permission": "job.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "job.read", + "x-immich-state": "Stable" }, "post": { "description": "Run a specific job. Most jobs are queued automatically, but this endpoint allows for manual creation of a handful of jobs, including various cleanup tasks, as well as creating a new database backup.", @@ -3783,7 +4918,22 @@ "Jobs" ], "x-immich-admin-only": true, - "x-immich-permission": "job.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "job.create", + "x-immich-state": "Stable" } }, "/jobs/{id}": { @@ -3838,7 +4988,22 @@ "Jobs" ], "x-immich-admin-only": true, - "x-immich-permission": "job.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "job.create", + "x-immich-state": "Stable" } }, "/libraries": { @@ -3877,7 +5042,22 @@ "Libraries" ], "x-immich-admin-only": true, - "x-immich-permission": "library.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "library.read", + "x-immich-state": "Stable" }, "post": { "description": "Create a new external library.", @@ -3921,7 +5101,22 @@ "Libraries" ], "x-immich-admin-only": true, - "x-immich-permission": "library.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "library.create", + "x-immich-state": "Stable" } }, "/libraries/{id}": { @@ -3960,7 +5155,22 @@ "Libraries" ], "x-immich-admin-only": true, - "x-immich-permission": "library.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "library.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve an external library by its ID.", @@ -4004,7 +5214,22 @@ "Libraries" ], "x-immich-admin-only": true, - "x-immich-permission": "library.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "library.read", + "x-immich-state": "Stable" }, "put": { "description": "Update an existing external library.", @@ -4058,7 +5283,22 @@ "Libraries" ], "x-immich-admin-only": true, - "x-immich-permission": "library.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "library.update", + "x-immich-state": "Stable" } }, "/libraries/{id}/scan": { @@ -4097,7 +5337,22 @@ "Libraries" ], "x-immich-admin-only": true, - "x-immich-permission": "library.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "library.update", + "x-immich-state": "Stable" } }, "/libraries/{id}/statistics": { @@ -4143,7 +5398,22 @@ "Libraries" ], "x-immich-admin-only": true, - "x-immich-permission": "library.statistics" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "library.statistics", + "x-immich-state": "Stable" } }, "/libraries/{id}/validate": { @@ -4198,7 +5468,22 @@ "tags": [ "Libraries" ], - "x-immich-admin-only": true + "x-immich-admin-only": true, + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/map/markers": { @@ -4286,7 +5571,22 @@ "summary": "Retrieve map markers", "tags": [ "Map" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/map/reverse-geocode": { @@ -4342,7 +5642,22 @@ "summary": "Reverse geocode coordinates", "tags": [ "Map" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/memories": { @@ -4432,7 +5747,22 @@ "tags": [ "Memories" ], - "x-immich-permission": "memory.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "memory.read", + "x-immich-state": "Stable" }, "post": { "description": "Create a new memory by providing a name, description, and a list of asset IDs to include in the memory.", @@ -4475,7 +5805,22 @@ "tags": [ "Memories" ], - "x-immich-permission": "memory.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "memory.create", + "x-immich-state": "Stable" } }, "/memories/statistics": { @@ -4562,7 +5907,22 @@ "tags": [ "Memories" ], - "x-immich-permission": "memory.statistics" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "memory.statistics", + "x-immich-state": "Stable" } }, "/memories/{id}": { @@ -4600,7 +5960,22 @@ "tags": [ "Memories" ], - "x-immich-permission": "memory.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "memory.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve a specific memory by its ID.", @@ -4643,7 +6018,22 @@ "tags": [ "Memories" ], - "x-immich-permission": "memory.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "memory.read", + "x-immich-state": "Stable" }, "put": { "description": "Update an existing memory by its ID.", @@ -4696,7 +6086,22 @@ "tags": [ "Memories" ], - "x-immich-permission": "memory.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "memory.update", + "x-immich-state": "Stable" } }, "/memories/{id}/assets": { @@ -4754,7 +6159,22 @@ "tags": [ "Memories" ], - "x-immich-permission": "memoryAsset.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "memoryAsset.delete", + "x-immich-state": "Stable" }, "put": { "description": "Add a list of asset IDs to a specific memory.", @@ -4810,7 +6230,22 @@ "tags": [ "Memories" ], - "x-immich-permission": "memoryAsset.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "memoryAsset.create", + "x-immich-state": "Stable" } }, "/notifications": { @@ -4848,7 +6283,22 @@ "tags": [ "Notifications" ], - "x-immich-permission": "notification.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "notification.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve a list of notifications.", @@ -4918,7 +6368,22 @@ "tags": [ "Notifications" ], - "x-immich-permission": "notification.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "notification.read", + "x-immich-state": "Stable" }, "put": { "description": "Update a list of notifications. Allows to bulk-set the read status of notifications.", @@ -4954,7 +6419,22 @@ "tags": [ "Notifications" ], - "x-immich-permission": "notification.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "notification.update", + "x-immich-state": "Stable" } }, "/notifications/{id}": { @@ -4992,7 +6472,22 @@ "tags": [ "Notifications" ], - "x-immich-permission": "notification.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "notification.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve a specific notification identified by id.", @@ -5035,7 +6530,22 @@ "tags": [ "Notifications" ], - "x-immich-permission": "notification.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "notification.read", + "x-immich-state": "Stable" }, "put": { "description": "Update a specific notification to set its read status.", @@ -5088,7 +6598,22 @@ "tags": [ "Notifications" ], - "x-immich-permission": "notification.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "notification.update", + "x-immich-state": "Stable" } }, "/oauth/authorize": { @@ -5121,7 +6646,22 @@ "summary": "Start OAuth", "tags": [ "Authentication" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/oauth/callback": { @@ -5154,7 +6694,22 @@ "summary": "Finish OAuth", "tags": [ "Authentication" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/oauth/link": { @@ -5198,7 +6753,22 @@ "summary": "Link OAuth account", "tags": [ "Authentication" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/oauth/mobile-redirect": { @@ -5214,7 +6784,22 @@ "summary": "Redirect OAuth to mobile", "tags": [ "Authentication" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/oauth/unlink": { @@ -5248,7 +6833,22 @@ "summary": "Unlink OAuth account", "tags": [ "Authentication" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/partners": { @@ -5295,7 +6895,22 @@ "tags": [ "Partners" ], - "x-immich-permission": "partner.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "partner.read", + "x-immich-state": "Stable" }, "post": { "description": "Create a new partner to share assets with.", @@ -5338,7 +6953,22 @@ "tags": [ "Partners" ], - "x-immich-permission": "partner.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "partner.create", + "x-immich-state": "Stable" } }, "/partners/{id}": { @@ -5376,11 +7006,26 @@ "tags": [ "Partners" ], - "x-immich-permission": "partner.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "partner.delete", + "x-immich-state": "Stable" }, "post": { "deprecated": true, - "description": "This property was deprecated in v1.141.0. Create a new partner to share assets with.", + "description": "Create a new partner to share assets with.", "operationId": "createPartnerDeprecated", "parameters": [ { @@ -5421,10 +7066,19 @@ "Partners", "Deprecated" ], - "x-immich-lifecycle": { - "deprecatedAt": "v1.141.0" - }, - "x-immich-permission": "partner.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Deprecated", + "replacementId": "createPartner" + } + ], + "x-immich-permission": "partner.create", + "x-immich-state": "Deprecated" }, "put": { "description": "Specify whether a partner's assets should appear in the user's timeline.", @@ -5477,7 +7131,22 @@ "tags": [ "Partners" ], - "x-immich-permission": "partner.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "partner.update", + "x-immich-state": "Stable" } }, "/people": { @@ -5515,7 +7184,22 @@ "tags": [ "People" ], - "x-immich-permission": "person.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "person.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve a list of all people.", @@ -5598,7 +7282,22 @@ "tags": [ "People" ], - "x-immich-permission": "person.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "person.read", + "x-immich-state": "Stable" }, "post": { "description": "Create a new person that can have multiple faces assigned to them.", @@ -5641,7 +7340,22 @@ "tags": [ "People" ], - "x-immich-permission": "person.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "person.create", + "x-immich-state": "Stable" }, "put": { "description": "Bulk update multiple people at once.", @@ -5687,7 +7401,22 @@ "tags": [ "People" ], - "x-immich-permission": "person.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "person.update", + "x-immich-state": "Stable" } }, "/people/{id}": { @@ -5725,7 +7454,22 @@ "tags": [ "People" ], - "x-immich-permission": "person.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "person.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve a person by id.", @@ -5768,7 +7512,22 @@ "tags": [ "People" ], - "x-immich-permission": "person.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "person.read", + "x-immich-state": "Stable" }, "put": { "description": "Update an individual person.", @@ -5821,7 +7580,22 @@ "tags": [ "People" ], - "x-immich-permission": "person.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "person.update", + "x-immich-state": "Stable" } }, "/people/{id}/merge": { @@ -5879,7 +7653,22 @@ "tags": [ "People" ], - "x-immich-permission": "person.merge" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "person.merge", + "x-immich-state": "Stable" } }, "/people/{id}/reassign": { @@ -5937,7 +7726,22 @@ "tags": [ "People" ], - "x-immich-permission": "person.reassign" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "person.reassign", + "x-immich-state": "Stable" } }, "/people/{id}/statistics": { @@ -5982,7 +7786,22 @@ "tags": [ "People" ], - "x-immich-permission": "person.statistics" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "person.statistics", + "x-immich-state": "Stable" } }, "/people/{id}/thumbnail": { @@ -6028,7 +7847,22 @@ "tags": [ "People" ], - "x-immich-permission": "person.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "person.read", + "x-immich-state": "Stable" } }, "/search/cities": { @@ -6066,7 +7900,22 @@ "tags": [ "Search" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Stable" } }, "/search/explore": { @@ -6104,7 +7953,22 @@ "tags": [ "Search" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Stable" } }, "/search/large-assets": { @@ -6432,7 +8296,22 @@ "tags": [ "Search" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Stable" } }, "/search/metadata": { @@ -6477,7 +8356,22 @@ "tags": [ "Search" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Stable" } }, "/search/person": { @@ -6532,7 +8426,22 @@ "tags": [ "Search" ], - "x-immich-permission": "person.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "person.read", + "x-immich-state": "Stable" } }, "/search/places": { @@ -6579,7 +8488,22 @@ "tags": [ "Search" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Stable" } }, "/search/random": { @@ -6627,7 +8551,22 @@ "tags": [ "Search" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Stable" } }, "/search/smart": { @@ -6672,7 +8611,22 @@ "tags": [ "Search" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Stable" } }, "/search/statistics": { @@ -6717,7 +8671,22 @@ "tags": [ "Search" ], - "x-immich-permission": "asset.statistics" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.statistics", + "x-immich-state": "Stable" } }, "/search/suggestions": { @@ -6737,7 +8706,17 @@ "name": "includeNull", "required": false, "in": "query", - "description": "This property was added in v111.0.0", + "x-immich-history": [ + { + "version": "v1.111.0", + "state": "Added" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable", "schema": { "type": "boolean" } @@ -6813,7 +8792,22 @@ "tags": [ "Search" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Stable" } }, "/server/about": { @@ -6848,7 +8842,22 @@ "tags": [ "Server" ], - "x-immich-permission": "server.about" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "server.about", + "x-immich-state": "Stable" } }, "/server/apk-links": { @@ -6883,7 +8892,22 @@ "tags": [ "Server" ], - "x-immich-permission": "server.apkLinks" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "server.apkLinks", + "x-immich-state": "Stable" } }, "/server/config": { @@ -6906,7 +8930,22 @@ "summary": "Get config", "tags": [ "Server" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/server/features": { @@ -6929,7 +8968,22 @@ "summary": "Get features", "tags": [ "Server" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/server/license": { @@ -6958,7 +9012,22 @@ "Server" ], "x-immich-admin-only": true, - "x-immich-permission": "serverLicense.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "serverLicense.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve information about whether the server currently has a product key registered.", @@ -6995,7 +9064,22 @@ "Server" ], "x-immich-admin-only": true, - "x-immich-permission": "serverLicense.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "serverLicense.read", + "x-immich-state": "Stable" }, "put": { "description": "Validate and set the server product key if successful.", @@ -7039,7 +9123,22 @@ "Server" ], "x-immich-admin-only": true, - "x-immich-permission": "serverLicense.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "serverLicense.update", + "x-immich-state": "Stable" } }, "/server/media-types": { @@ -7062,7 +9161,22 @@ "summary": "Get supported media types", "tags": [ "Server" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/server/ping": { @@ -7085,7 +9199,22 @@ "summary": "Ping", "tags": [ "Server" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/server/statistics": { @@ -7121,7 +9250,22 @@ "Server" ], "x-immich-admin-only": true, - "x-immich-permission": "server.statistics" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "server.statistics", + "x-immich-state": "Stable" } }, "/server/storage": { @@ -7156,7 +9300,22 @@ "tags": [ "Server" ], - "x-immich-permission": "server.storage" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "server.storage", + "x-immich-state": "Stable" } }, "/server/theme": { @@ -7179,7 +9338,22 @@ "summary": "Get theme", "tags": [ "Server" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/server/version": { @@ -7202,7 +9376,22 @@ "summary": "Get server version", "tags": [ "Server" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/server/version-check": { @@ -7237,7 +9426,22 @@ "tags": [ "Server" ], - "x-immich-permission": "server.versionCheck" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "server.versionCheck", + "x-immich-state": "Stable" } }, "/server/version-history": { @@ -7263,7 +9467,22 @@ "summary": "Get version history", "tags": [ "Server" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/sessions": { @@ -7291,7 +9510,22 @@ "tags": [ "Sessions" ], - "x-immich-permission": "session.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "session.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve a list of sessions for the user.", @@ -7327,7 +9561,22 @@ "tags": [ "Sessions" ], - "x-immich-permission": "session.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "session.read", + "x-immich-state": "Stable" }, "post": { "description": "Create a session as a child to the current session. This endpoint is used for casting.", @@ -7370,7 +9619,22 @@ "tags": [ "Sessions" ], - "x-immich-permission": "session.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "session.create", + "x-immich-state": "Stable" } }, "/sessions/{id}": { @@ -7408,7 +9672,22 @@ "tags": [ "Sessions" ], - "x-immich-permission": "session.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "session.delete", + "x-immich-state": "Stable" }, "put": { "description": "Update a specific session identified by id.", @@ -7461,7 +9740,22 @@ "tags": [ "Sessions" ], - "x-immich-permission": "session.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "session.update", + "x-immich-state": "Stable" } }, "/sessions/{id}/lock": { @@ -7499,7 +9793,22 @@ "tags": [ "Sessions" ], - "x-immich-permission": "session.lock" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "session.lock", + "x-immich-state": "Stable" } }, "/shared-links": { @@ -7547,7 +9856,22 @@ "tags": [ "Shared links" ], - "x-immich-permission": "sharedLink.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "sharedLink.read", + "x-immich-state": "Stable" }, "post": { "description": "Create a new shared link.", @@ -7590,7 +9914,22 @@ "tags": [ "Shared links" ], - "x-immich-permission": "sharedLink.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "sharedLink.create", + "x-immich-state": "Stable" } }, "/shared-links/me": { @@ -7658,7 +9997,22 @@ "summary": "Retrieve current shared link", "tags": [ "Shared links" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/shared-links/{id}": { @@ -7696,7 +10050,22 @@ "tags": [ "Shared links" ], - "x-immich-permission": "sharedLink.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "sharedLink.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve a specific shared link by its ID.", @@ -7739,7 +10108,22 @@ "tags": [ "Shared links" ], - "x-immich-permission": "sharedLink.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "sharedLink.read", + "x-immich-state": "Stable" }, "patch": { "description": "Update an existing shared link by its ID.", @@ -7792,7 +10176,22 @@ "tags": [ "Shared links" ], - "x-immich-permission": "sharedLink.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "sharedLink.update", + "x-immich-state": "Stable" } }, "/shared-links/{id}/assets": { @@ -7865,7 +10264,22 @@ "summary": "Remove assets from a shared link", "tags": [ "Shared links" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" }, "put": { "description": "Add assets to a specific shared link by its ID. This endpoint is only relevant for shared link of type individual.", @@ -7936,7 +10350,22 @@ "summary": "Add assets to a shared link", "tags": [ "Shared links" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/stacks": { @@ -7974,7 +10403,22 @@ "tags": [ "Stacks" ], - "x-immich-permission": "stack.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "stack.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve a list of stacks.", @@ -8020,7 +10464,22 @@ "tags": [ "Stacks" ], - "x-immich-permission": "stack.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "stack.read", + "x-immich-state": "Stable" }, "post": { "description": "Create a new stack by providing a name and a list of asset IDs to include in the stack. If any of the provided asset IDs are primary assets of an existing stack, the existing stack will be merged into the newly created stack.", @@ -8063,7 +10522,22 @@ "tags": [ "Stacks" ], - "x-immich-permission": "stack.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "stack.create", + "x-immich-state": "Stable" } }, "/stacks/{id}": { @@ -8101,7 +10575,22 @@ "tags": [ "Stacks" ], - "x-immich-permission": "stack.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "stack.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve a specific stack by its ID.", @@ -8144,7 +10633,22 @@ "tags": [ "Stacks" ], - "x-immich-permission": "stack.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "stack.read", + "x-immich-state": "Stable" }, "put": { "description": "Update an existing stack by its ID.", @@ -8197,7 +10701,22 @@ "tags": [ "Stacks" ], - "x-immich-permission": "stack.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "stack.update", + "x-immich-state": "Stable" } }, "/stacks/{id}/assets/{assetId}": { @@ -8244,7 +10763,22 @@ "tags": [ "Stacks" ], - "x-immich-permission": "stack.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "stack.update", + "x-immich-state": "Stable" } }, "/sync/ack": { @@ -8282,7 +10816,22 @@ "tags": [ "Sync" ], - "x-immich-permission": "syncCheckpoint.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "syncCheckpoint.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve the synchronization acknowledgments for the current session.", @@ -8318,7 +10867,22 @@ "tags": [ "Sync" ], - "x-immich-permission": "syncCheckpoint.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "syncCheckpoint.read", + "x-immich-state": "Stable" }, "post": { "description": "Send a list of synchronization acknowledgements to confirm that the latest changes have been received.", @@ -8354,13 +10918,28 @@ "tags": [ "Sync" ], - "x-immich-permission": "syncCheckpoint.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "syncCheckpoint.update", + "x-immich-state": "Stable" } }, "/sync/delta-sync": { "post": { "deprecated": true, - "description": "This property was deprecated in v2.0.0. Retrieve changed assets since the last sync for the authenticated user.", + "description": "Retrieve changed assets since the last sync for the authenticated user.", "operationId": "getDeltaSync", "parameters": [], "requestBody": { @@ -8401,15 +10980,23 @@ "Sync", "Deprecated" ], - "x-immich-lifecycle": { - "deprecatedAt": "v2.0.0" - } + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v2", + "state": "Deprecated" + } + ], + "x-immich-state": "Deprecated" } }, "/sync/full-sync": { "post": { "deprecated": true, - "description": "This property was deprecated in v2.0.0. Retrieve all assets for a full synchronization for the authenticated user.", + "description": "Retrieve all assets for a full synchronization for the authenticated user.", "operationId": "getFullSyncForUser", "parameters": [], "requestBody": { @@ -8453,9 +11040,17 @@ "Sync", "Deprecated" ], - "x-immich-lifecycle": { - "deprecatedAt": "v2.0.0" - } + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v2", + "state": "Deprecated" + } + ], + "x-immich-state": "Deprecated" } }, "/sync/stream": { @@ -8493,7 +11088,22 @@ "tags": [ "Sync" ], - "x-immich-permission": "sync.stream" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "sync.stream", + "x-immich-state": "Stable" } }, "/system-config": { @@ -8529,7 +11139,22 @@ "System config" ], "x-immich-admin-only": true, - "x-immich-permission": "systemConfig.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "systemConfig.read", + "x-immich-state": "Stable" }, "put": { "description": "Update the system configuration with a new system configuration.", @@ -8573,7 +11198,22 @@ "System config" ], "x-immich-admin-only": true, - "x-immich-permission": "systemConfig.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "systemConfig.update", + "x-immich-state": "Stable" } }, "/system-config/defaults": { @@ -8609,7 +11249,22 @@ "System config" ], "x-immich-admin-only": true, - "x-immich-permission": "systemConfig.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "systemConfig.read", + "x-immich-state": "Stable" } }, "/system-config/storage-template-options": { @@ -8645,7 +11300,22 @@ "System config" ], "x-immich-admin-only": true, - "x-immich-permission": "systemConfig.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "systemConfig.read", + "x-immich-state": "Stable" } }, "/system-metadata/admin-onboarding": { @@ -8681,7 +11351,22 @@ "System metadata" ], "x-immich-admin-only": true, - "x-immich-permission": "systemMetadata.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "systemMetadata.read", + "x-immich-state": "Stable" }, "post": { "description": "Update the admin onboarding status.", @@ -8718,7 +11403,22 @@ "System metadata" ], "x-immich-admin-only": true, - "x-immich-permission": "systemMetadata.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "systemMetadata.update", + "x-immich-state": "Stable" } }, "/system-metadata/reverse-geocoding-state": { @@ -8754,7 +11454,22 @@ "System metadata" ], "x-immich-admin-only": true, - "x-immich-permission": "systemMetadata.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "systemMetadata.read", + "x-immich-state": "Stable" } }, "/system-metadata/version-check-state": { @@ -8790,7 +11505,22 @@ "System metadata" ], "x-immich-admin-only": true, - "x-immich-permission": "systemMetadata.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "systemMetadata.read", + "x-immich-state": "Stable" } }, "/tags": { @@ -8828,7 +11558,22 @@ "tags": [ "Tags" ], - "x-immich-permission": "tag.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "tag.read", + "x-immich-state": "Stable" }, "post": { "description": "Create a new tag by providing a name and optional color.", @@ -8871,7 +11616,22 @@ "tags": [ "Tags" ], - "x-immich-permission": "tag.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "tag.create", + "x-immich-state": "Stable" }, "put": { "description": "Create or update multiple tags in a single request.", @@ -8917,7 +11677,22 @@ "tags": [ "Tags" ], - "x-immich-permission": "tag.create" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "tag.create", + "x-immich-state": "Stable" } }, "/tags/assets": { @@ -8962,7 +11737,22 @@ "tags": [ "Tags" ], - "x-immich-permission": "tag.asset" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "tag.asset", + "x-immich-state": "Stable" } }, "/tags/{id}": { @@ -9000,7 +11790,22 @@ "tags": [ "Tags" ], - "x-immich-permission": "tag.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "tag.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve a specific tag by its ID.", @@ -9043,7 +11848,22 @@ "tags": [ "Tags" ], - "x-immich-permission": "tag.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "tag.read", + "x-immich-state": "Stable" }, "put": { "description": "Update an existing tag identified by its ID.", @@ -9096,7 +11916,22 @@ "tags": [ "Tags" ], - "x-immich-permission": "tag.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "tag.update", + "x-immich-state": "Stable" } }, "/tags/{id}/assets": { @@ -9154,7 +11989,22 @@ "tags": [ "Tags" ], - "x-immich-permission": "tag.asset" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "tag.asset", + "x-immich-state": "Stable" }, "put": { "description": "Add a tag to all the specified assets.", @@ -9210,7 +12060,22 @@ "tags": [ "Tags" ], - "x-immich-permission": "tag.asset" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "tag.asset", + "x-immich-state": "Stable" } }, "/timeline/bucket": { @@ -9375,7 +12240,18 @@ "tags": [ "Timeline" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Internal" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Internal" } }, "/timeline/buckets": { @@ -9533,7 +12409,18 @@ "tags": [ "Timeline" ], - "x-immich-permission": "asset.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Internal" + } + ], + "x-immich-permission": "asset.read", + "x-immich-state": "Internal" } }, "/trash/empty": { @@ -9568,7 +12455,22 @@ "tags": [ "Trash" ], - "x-immich-permission": "asset.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.delete", + "x-immich-state": "Stable" } }, "/trash/restore": { @@ -9603,7 +12505,22 @@ "tags": [ "Trash" ], - "x-immich-permission": "asset.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.delete", + "x-immich-state": "Stable" } }, "/trash/restore/assets": { @@ -9648,7 +12565,22 @@ "tags": [ "Trash" ], - "x-immich-permission": "asset.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "asset.delete", + "x-immich-state": "Stable" } }, "/users": { @@ -9686,7 +12618,22 @@ "tags": [ "Users" ], - "x-immich-permission": "user.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "user.read", + "x-immich-state": "Stable" } }, "/users/me": { @@ -9721,7 +12668,22 @@ "tags": [ "Users" ], - "x-immich-permission": "user.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "user.read", + "x-immich-state": "Stable" }, "put": { "description": "Update the current user making teh API request.", @@ -9764,7 +12726,22 @@ "tags": [ "Users" ], - "x-immich-permission": "user.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "user.update", + "x-immich-state": "Stable" } }, "/users/me/license": { @@ -9792,7 +12769,22 @@ "tags": [ "Users" ], - "x-immich-permission": "userLicense.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "userLicense.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve information about whether the current user has a registered product key.", @@ -9825,7 +12817,22 @@ "tags": [ "Users" ], - "x-immich-permission": "userLicense.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "userLicense.read", + "x-immich-state": "Stable" }, "put": { "description": "Register a product key for the current user.", @@ -9868,7 +12875,22 @@ "tags": [ "Users" ], - "x-immich-permission": "userLicense.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "userLicense.update", + "x-immich-state": "Stable" } }, "/users/me/onboarding": { @@ -9896,7 +12918,22 @@ "tags": [ "Users" ], - "x-immich-permission": "userOnboarding.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "userOnboarding.delete", + "x-immich-state": "Stable" }, "get": { "description": "Retrieve the onboarding status of the current user.", @@ -9929,7 +12966,22 @@ "tags": [ "Users" ], - "x-immich-permission": "userOnboarding.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "userOnboarding.read", + "x-immich-state": "Stable" }, "put": { "description": "Update the onboarding status of the current user.", @@ -9972,7 +13024,22 @@ "tags": [ "Users" ], - "x-immich-permission": "userOnboarding.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "userOnboarding.update", + "x-immich-state": "Stable" } }, "/users/me/preferences": { @@ -10007,7 +13074,22 @@ "tags": [ "Users" ], - "x-immich-permission": "userPreference.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "userPreference.read", + "x-immich-state": "Stable" }, "put": { "description": "Update the preferences of the current user.", @@ -10050,7 +13132,22 @@ "tags": [ "Users" ], - "x-immich-permission": "userPreference.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "userPreference.update", + "x-immich-state": "Stable" } }, "/users/profile-image": { @@ -10078,7 +13175,22 @@ "tags": [ "Users" ], - "x-immich-permission": "userProfileImage.delete" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "userProfileImage.delete", + "x-immich-state": "Stable" }, "post": { "description": "Upload and set a new profile image for the current user.", @@ -10122,7 +13234,22 @@ "tags": [ "Users" ], - "x-immich-permission": "userProfileImage.update" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "userProfileImage.update", + "x-immich-state": "Stable" } }, "/users/{id}": { @@ -10167,7 +13294,22 @@ "tags": [ "Users" ], - "x-immich-permission": "user.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "user.read", + "x-immich-state": "Stable" } }, "/users/{id}/profile-image": { @@ -10213,7 +13355,22 @@ "tags": [ "Users" ], - "x-immich-permission": "userProfileImage.read" + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-permission": "userProfileImage.read", + "x-immich-state": "Stable" } }, "/view/folder": { @@ -10259,7 +13416,22 @@ "summary": "Retrieve assets by original path", "tags": [ "Views" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "/view/folder/unique-paths": { @@ -10296,7 +13468,22 @@ "summary": "Retrieve unique paths", "tags": [ "Views" - ] + ], + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Beta" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } } }, @@ -11813,9 +15000,19 @@ }, "libraryId": { "deprecated": true, - "description": "This property was deprecated in v1.106.0", "nullable": true, - "type": "string" + "type": "string", + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1", + "state": "Deprecated" + } + ], + "x-immich-state": "Deprecated" }, "livePhotoVideoId": { "nullable": true, @@ -11850,8 +15047,18 @@ }, "resized": { "deprecated": true, - "description": "This property was deprecated in v1.113.0", - "type": "boolean" + "type": "boolean", + "x-immich-history": [ + { + "version": "v1", + "state": "Added" + }, + { + "version": "v1.113.0", + "state": "Deprecated" + } + ], + "x-immich-state": "Deprecated" }, "stack": { "allOf": [ @@ -13808,8 +17015,18 @@ "PeopleResponseDto": { "properties": { "hasNextPage": { - "description": "This property was added in v1.110.0", - "type": "boolean" + "type": "boolean", + "x-immich-history": [ + { + "version": "v1.110.0", + "state": "Added" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" }, "hidden": { "type": "integer" @@ -14063,15 +17280,35 @@ "type": "string" }, "color": { - "description": "This property was added in v1.126.0", - "type": "string" + "type": "string", + "x-immich-history": [ + { + "version": "v1.126.0", + "state": "Added" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" }, "id": { "type": "string" }, "isFavorite": { - "description": "This property was added in v1.126.0", - "type": "boolean" + "type": "boolean", + "x-immich-history": [ + { + "version": "v1.126.0", + "state": "Added" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" }, "isHidden": { "type": "boolean" @@ -14083,9 +17320,19 @@ "type": "string" }, "updatedAt": { - "description": "This property was added in v1.107.0", "format": "date-time", - "type": "string" + "type": "string", + "x-immich-history": [ + { + "version": "v1.107.0", + "state": "Added" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "required": [ @@ -14147,8 +17394,18 @@ "type": "string" }, "color": { - "description": "This property was added in v1.126.0", - "type": "string" + "type": "string", + "x-immich-history": [ + { + "version": "v1.126.0", + "state": "Added" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" }, "faces": { "items": { @@ -14160,8 +17417,18 @@ "type": "string" }, "isFavorite": { - "description": "This property was added in v1.126.0", - "type": "boolean" + "type": "boolean", + "x-immich-history": [ + { + "version": "v1.126.0", + "state": "Added" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" }, "isHidden": { "type": "boolean" @@ -14173,9 +17440,19 @@ "type": "string" }, "updatedAt": { - "description": "This property was added in v1.107.0", "format": "date-time", - "type": "string" + "type": "string", + "x-immich-history": [ + { + "version": "v1.107.0", + "state": "Added" + }, + { + "version": "v2", + "state": "Stable" + } + ], + "x-immich-state": "Stable" } }, "required": [ diff --git a/open-api/typescript-sdk/src/fetch-client.ts b/open-api/typescript-sdk/src/fetch-client.ts index eed7b27088..9aec8b6f87 100644 --- a/open-api/typescript-sdk/src/fetch-client.ts +++ b/open-api/typescript-sdk/src/fetch-client.ts @@ -302,16 +302,13 @@ export type AssetFaceWithoutPersonResponseDto = { }; export type PersonWithFacesResponseDto = { birthDate: string | null; - /** This property was added in v1.126.0 */ color?: string; faces: AssetFaceWithoutPersonResponseDto[]; id: string; - /** This property was added in v1.126.0 */ isFavorite?: boolean; isHidden: boolean; name: string; thumbnailPath: string; - /** This property was added in v1.107.0 */ updatedAt?: string; }; export type AssetStackResponseDto = { @@ -348,7 +345,6 @@ export type AssetResponseDto = { isFavorite: boolean; isOffline: boolean; isTrashed: boolean; - /** This property was deprecated in v1.106.0 */ libraryId?: string | null; livePhotoVideoId?: string | null; /** The local date and time when the photo/video was taken, derived from EXIF metadata. This represents the photographer's local time regardless of timezone, stored as a timezone-agnostic timestamp. Used for timeline grouping by "local" days and months. */ @@ -359,7 +355,6 @@ export type AssetResponseDto = { owner?: UserResponseDto; ownerId: string; people?: PersonWithFacesResponseDto[]; - /** This property was deprecated in v1.113.0 */ resized?: boolean; stack?: (AssetStackResponseDto) | null; tags?: TagResponseDto[]; @@ -669,15 +664,12 @@ export type DuplicateResponseDto = { }; export type PersonResponseDto = { birthDate: string | null; - /** This property was added in v1.126.0 */ color?: string; id: string; - /** This property was added in v1.126.0 */ isFavorite?: boolean; isHidden: boolean; name: string; thumbnailPath: string; - /** This property was added in v1.107.0 */ updatedAt?: string; }; export type AssetFaceResponseDto = { @@ -874,7 +866,6 @@ export type PartnerUpdateDto = { inTimeline: boolean; }; export type PeopleResponseDto = { - /** This property was added in v1.110.0 */ hasNextPage?: boolean; hidden: number; people: PersonResponseDto[]; diff --git a/server/package.json b/server/package.json index 0a8130163e..c94f1376a1 100644 --- a/server/package.json +++ b/server/package.json @@ -22,7 +22,6 @@ "test:cov": "vitest --config test/vitest.config.mjs --coverage", "test:medium": "vitest --config test/vitest.config.medium.mjs", "typeorm": "typeorm", - "lifecycle": "node ./dist/utils/lifecycle.js", "migrations:debug": "node ./dist/bin/migrations.js debug", "migrations:generate": "node ./dist/bin/migrations.js generate", "migrations:create": "node ./dist/bin/migrations.js create", diff --git a/server/src/constants.ts b/server/src/constants.ts index 1a14bdbcc3..ddf8bc91d1 100644 --- a/server/src/constants.ts +++ b/server/src/constants.ts @@ -9,11 +9,6 @@ export const VECTORCHORD_VERSION_RANGE = '>=0.3 <0.6'; export const VECTORS_VERSION_RANGE = '>=0.2 <0.4'; export const VECTOR_VERSION_RANGE = '>=0.5 <1'; -export const NEXT_RELEASE = 'NEXT_RELEASE'; -export const LIFECYCLE_EXTENSION = 'x-immich-lifecycle'; -export const DEPRECATED_IN_PREFIX = 'This property was deprecated in '; -export const ADDED_IN_PREFIX = 'This property was added in '; - export const JOBS_ASSET_PAGINATION_SIZE = 1000; export const JOBS_LIBRARY_PAGINATION_SIZE = 10_000; diff --git a/server/src/controllers/activity.controller.ts b/server/src/controllers/activity.controller.ts index e0c71a00e6..850e95510f 100644 --- a/server/src/controllers/activity.controller.ts +++ b/server/src/controllers/activity.controller.ts @@ -1,6 +1,7 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Query, Res } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; import { Response } from 'express'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { ActivityCreateDto, ActivityDto, @@ -21,10 +22,11 @@ export class ActivityController { @Get() @Authenticated({ permission: Permission.ActivityRead }) - @ApiOperation({ + @Endpoint({ summary: 'List all activities', description: 'Returns a list of activities for the selected asset or album. The activities are returned in sorted order, with the oldest activities appearing first.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getActivities(@Auth() auth: AuthDto, @Query() dto: ActivitySearchDto): Promise { return this.service.getAll(auth, dto); @@ -32,9 +34,10 @@ export class ActivityController { @Post() @Authenticated({ permission: Permission.ActivityCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Create an activity', description: 'Create a like or a comment for an album, or an asset in an album.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async createActivity( @Auth() auth: AuthDto, @@ -50,9 +53,10 @@ export class ActivityController { @Get('statistics') @Authenticated({ permission: Permission.ActivityStatistics }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve activity statistics', description: 'Returns the number of likes and comments for a given album or asset in an album.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getActivityStatistics(@Auth() auth: AuthDto, @Query() dto: ActivityDto): Promise { return this.service.getStatistics(auth, dto); @@ -61,9 +65,10 @@ export class ActivityController { @Delete(':id') @Authenticated({ permission: Permission.ActivityDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete an activity', description: 'Removes a like or comment from a given album or asset in an album.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteActivity(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.delete(auth, id); diff --git a/server/src/controllers/album.controller.ts b/server/src/controllers/album.controller.ts index 671aa55004..dad70257a7 100644 --- a/server/src/controllers/album.controller.ts +++ b/server/src/controllers/album.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Patch, Post, Put, Query } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AddUsersDto, AlbumInfoDto, @@ -26,9 +27,10 @@ export class AlbumController { @Get() @Authenticated({ permission: Permission.AlbumRead }) - @ApiOperation({ + @Endpoint({ summary: 'List all albums', description: 'Retrieve a list of albums available to the authenticated user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAllAlbums(@Auth() auth: AuthDto, @Query() query: GetAlbumsDto): Promise { return this.service.getAll(auth, query); @@ -36,9 +38,10 @@ export class AlbumController { @Post() @Authenticated({ permission: Permission.AlbumCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Create an album', description: 'Create a new album. The album can also be created with initial users and assets.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createAlbum(@Auth() auth: AuthDto, @Body() dto: CreateAlbumDto): Promise { return this.service.create(auth, dto); @@ -46,9 +49,10 @@ export class AlbumController { @Get('statistics') @Authenticated({ permission: Permission.AlbumStatistics }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve album statistics', description: 'Returns statistics about the albums available to the authenticated user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAlbumStatistics(@Auth() auth: AuthDto): Promise { return this.service.getStatistics(auth); @@ -56,9 +60,10 @@ export class AlbumController { @Authenticated({ permission: Permission.AlbumRead, sharedLink: true }) @Get(':id') - @ApiOperation({ + @Endpoint({ summary: 'Retrieve an album', description: 'Retrieve information about a specific album by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAlbumInfo( @Auth() auth: AuthDto, @@ -70,10 +75,11 @@ export class AlbumController { @Patch(':id') @Authenticated({ permission: Permission.AlbumUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Update an album', description: 'Update the information of a specific album by its ID. This endpoint can be used to update the album name, description, sort order, etc. However, it is not used to add or remove assets or users from the album.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateAlbumInfo( @Auth() auth: AuthDto, @@ -86,10 +92,11 @@ export class AlbumController { @Delete(':id') @Authenticated({ permission: Permission.AlbumDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete an album', description: 'Delete a specific album by its ID. Note the album is initially trashed and then immediately scheduled for deletion, but relies on a background job to complete the process.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteAlbum(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto) { return this.service.delete(auth, id); @@ -97,9 +104,10 @@ export class AlbumController { @Put(':id/assets') @Authenticated({ permission: Permission.AlbumAssetCreate, sharedLink: true }) - @ApiOperation({ + @Endpoint({ summary: 'Add assets to an album', description: 'Add multiple assets to a specific album by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) addAssetsToAlbum( @Auth() auth: AuthDto, @@ -111,9 +119,10 @@ export class AlbumController { @Put('assets') @Authenticated({ permission: Permission.AlbumAssetCreate, sharedLink: true }) - @ApiOperation({ + @Endpoint({ summary: 'Add assets to albums', description: 'Send a list of asset IDs and album IDs to add each asset to each album.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) addAssetsToAlbums(@Auth() auth: AuthDto, @Body() dto: AlbumsAddAssetsDto): Promise { return this.service.addAssetsToAlbums(auth, dto); @@ -121,9 +130,10 @@ export class AlbumController { @Delete(':id/assets') @Authenticated({ permission: Permission.AlbumAssetDelete }) - @ApiOperation({ + @Endpoint({ summary: 'Remove assets from an album', description: 'Remove multiple assets from a specific album by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) removeAssetFromAlbum( @Auth() auth: AuthDto, @@ -135,9 +145,10 @@ export class AlbumController { @Put(':id/users') @Authenticated({ permission: Permission.AlbumUserCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Share album with users', description: 'Share an album with multiple users. Each user can be given a specific role in the album.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) addUsersToAlbum( @Auth() auth: AuthDto, @@ -150,9 +161,10 @@ export class AlbumController { @Put(':id/user/:userId') @Authenticated({ permission: Permission.AlbumUserUpdate }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Update user role', description: 'Change the role for a specific user in a specific album.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateAlbumUser( @Auth() auth: AuthDto, @@ -166,9 +178,10 @@ export class AlbumController { @Delete(':id/user/:userId') @Authenticated({ permission: Permission.AlbumUserDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Remove user from album', description: 'Remove a user from an album. Use an ID of "me" to leave a shared album.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) removeUserFromAlbum( @Auth() auth: AuthDto, diff --git a/server/src/controllers/api-key.controller.ts b/server/src/controllers/api-key.controller.ts index 8a4e01e36a..61ad203331 100644 --- a/server/src/controllers/api-key.controller.ts +++ b/server/src/controllers/api-key.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { APIKeyCreateDto, APIKeyCreateResponseDto, APIKeyResponseDto, APIKeyUpdateDto } from 'src/dtos/api-key.dto'; import { AuthDto } from 'src/dtos/auth.dto'; import { ApiTag, Permission } from 'src/enum'; @@ -14,9 +15,10 @@ export class ApiKeyController { @Post() @Authenticated({ permission: Permission.ApiKeyCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Create an API key', description: 'Creates a new API key. It will be limited to the permissions specified.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createApiKey(@Auth() auth: AuthDto, @Body() dto: APIKeyCreateDto): Promise { return this.service.create(auth, dto); @@ -24,16 +26,21 @@ export class ApiKeyController { @Get() @Authenticated({ permission: Permission.ApiKeyRead }) - @ApiOperation({ summary: 'List all API keys', description: 'Retrieve all API keys of the current user.' }) + @Endpoint({ + summary: 'List all API keys', + description: 'Retrieve all API keys of the current user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) getApiKeys(@Auth() auth: AuthDto): Promise { return this.service.getAll(auth); } @Get('me') @Authenticated({ permission: false }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve the current API key', description: 'Retrieve the API key that is used to access this endpoint.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async getMyApiKey(@Auth() auth: AuthDto): Promise { return this.service.getMine(auth); @@ -41,9 +48,10 @@ export class ApiKeyController { @Get(':id') @Authenticated({ permission: Permission.ApiKeyRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve an API key', description: 'Retrieve an API key by its ID. The current user must own this API key.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getApiKey(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.getById(auth, id); @@ -51,9 +59,10 @@ export class ApiKeyController { @Put(':id') @Authenticated({ permission: Permission.ApiKeyUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Update an API key', description: 'Updates the name and permissions of an API key by its ID. The current user must own this API key.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateApiKey( @Auth() auth: AuthDto, @@ -66,9 +75,10 @@ export class ApiKeyController { @Delete(':id') @Authenticated({ permission: Permission.ApiKeyDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete an API key', description: 'Deletes an API key identified by its ID. The current user must own this API key.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteApiKey(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.delete(auth, id); diff --git a/server/src/controllers/asset-media.controller.ts b/server/src/controllers/asset-media.controller.ts index 6f110b33ba..843c2a3f3d 100644 --- a/server/src/controllers/asset-media.controller.ts +++ b/server/src/controllers/asset-media.controller.ts @@ -15,9 +15,9 @@ import { UploadedFiles, UseInterceptors, } from '@nestjs/common'; -import { ApiBody, ApiConsumes, ApiHeader, ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiBody, ApiConsumes, ApiHeader, ApiTags } from '@nestjs/swagger'; import { NextFunction, Request, Response } from 'express'; -import { EndpointLifecycle } from 'src/decorators'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AssetBulkUploadCheckResponseDto, AssetMediaResponseDto, @@ -62,9 +62,10 @@ export class AssetMediaController { required: false, }) @ApiBody({ description: 'Asset Upload Information', type: AssetMediaCreateDto }) - @ApiOperation({ + @Endpoint({ summary: 'Upload asset', description: 'Uploads a new asset to the server.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async uploadAsset( @Auth() auth: AuthDto, @@ -85,9 +86,10 @@ export class AssetMediaController { @Get(':id/original') @FileResponse() @Authenticated({ permission: Permission.AssetDownload, sharedLink: true }) - @ApiOperation({ + @Endpoint({ summary: 'Download original asset', description: 'Downloads the original file of the specified asset.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async downloadAsset( @Auth() auth: AuthDto, @@ -101,11 +103,10 @@ export class AssetMediaController { @Put(':id/original') @UseInterceptors(FileUploadInterceptor) @ApiConsumes('multipart/form-data') - @EndpointLifecycle({ - addedAt: 'v1.106.0', - deprecatedAt: 'v1.142.0', + @Endpoint({ summary: 'Replace asset', description: 'Replace the asset with new file, without changing its id.', + history: new HistoryBuilder().added('v1').deprecated('v1', { replacementId: 'copyAsset' }), }) @Authenticated({ permission: Permission.AssetReplace, sharedLink: true }) async replaceAsset( @@ -127,9 +128,10 @@ export class AssetMediaController { @Get(':id/thumbnail') @FileResponse() @Authenticated({ permission: Permission.AssetView, sharedLink: true }) - @ApiOperation({ + @Endpoint({ summary: 'View asset thumbnail', description: 'Retrieve the thumbnail image for the specified asset.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async viewAsset( @Auth() auth: AuthDto, @@ -168,9 +170,10 @@ export class AssetMediaController { @Get(':id/video/playback') @FileResponse() @Authenticated({ permission: Permission.AssetView, sharedLink: true }) - @ApiOperation({ + @Endpoint({ summary: 'Play asset video', description: 'Streams the video file for the specified asset. This endpoint also supports byte range requests.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async playAssetVideo( @Auth() auth: AuthDto, @@ -181,14 +184,12 @@ export class AssetMediaController { await sendFile(res, next, () => this.service.playbackVideo(auth, id), this.logger); } - /** - * Checks if multiple assets exist on the server and returns all existing - used by background backup - */ @Post('exist') @Authenticated() - @ApiOperation({ + @Endpoint({ summary: 'Check existing assets', description: 'Checks if multiple assets exist on the server and returns all existing - used by background backup', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) @HttpCode(HttpStatus.OK) checkExistingAssets( @@ -198,14 +199,12 @@ export class AssetMediaController { return this.service.checkExistingAssets(auth, dto); } - /** - * Checks if assets exist by checksums - */ @Post('bulk-upload-check') @Authenticated({ permission: Permission.AssetUpload }) - @ApiOperation({ + @Endpoint({ summary: 'Check bulk upload', description: 'Determine which assets have already been uploaded to the server based on their SHA1 checksums.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) @HttpCode(HttpStatus.OK) checkBulkUpload( diff --git a/server/src/controllers/asset.controller.ts b/server/src/controllers/asset.controller.ts index 6a7309b6d6..bcc13fbc06 100644 --- a/server/src/controllers/asset.controller.ts +++ b/server/src/controllers/asset.controller.ts @@ -1,6 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put, Query } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; -import { EndpointLifecycle } from 'src/decorators'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AssetResponseDto } from 'src/dtos/asset-response.dto'; import { AssetBulkDeleteDto, @@ -30,20 +30,20 @@ export class AssetController { @Get('random') @Authenticated({ permission: Permission.AssetRead }) - @EndpointLifecycle({ - deprecatedAt: 'v1.116.0', + @Endpoint({ summary: 'Get random assets', description: 'Retrieve a specified number of random assets for the authenticated user.', + history: new HistoryBuilder().added('v1').deprecated('v1', { replacementId: 'searchAssets' }), }) getRandom(@Auth() auth: AuthDto, @Query() dto: RandomAssetsDto): Promise { return this.service.getRandom(auth, dto.count ?? 1); } @Get('/device/:deviceId') - @EndpointLifecycle({ - deprecatedAt: 'v2.0.0', + @Endpoint({ summary: 'Retrieve assets by device ID', description: 'Get all asset of a device that are in the database, ID only.', + history: new HistoryBuilder().added('v1').deprecated('v2'), }) @Authenticated() getAllUserAssetsByDeviceId(@Auth() auth: AuthDto, @Param() { deviceId }: DeviceIdDto) { @@ -52,9 +52,10 @@ export class AssetController { @Get('statistics') @Authenticated({ permission: Permission.AssetStatistics }) - @ApiOperation({ + @Endpoint({ summary: 'Get asset statistics', description: 'Retrieve various statistics about the assets owned by the authenticated user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAssetStatistics(@Auth() auth: AuthDto, @Query() dto: AssetStatsDto): Promise { return this.service.getStatistics(auth, dto); @@ -63,9 +64,10 @@ export class AssetController { @Post('jobs') @Authenticated() @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Run an asset job', description: 'Run a specific job on a set of assets.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) runAssetJobs(@Auth() auth: AuthDto, @Body() dto: AssetJobsDto): Promise { return this.service.run(auth, dto); @@ -74,9 +76,10 @@ export class AssetController { @Put() @Authenticated({ permission: Permission.AssetUpdate }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Update assets', description: 'Updates multiple assets at the same time.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateAssets(@Auth() auth: AuthDto, @Body() dto: AssetBulkUpdateDto): Promise { return this.service.updateAll(auth, dto); @@ -85,9 +88,10 @@ export class AssetController { @Delete() @Authenticated({ permission: Permission.AssetDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete assets', description: 'Deletes multiple assets at the same time.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteAssets(@Auth() auth: AuthDto, @Body() dto: AssetBulkDeleteDto): Promise { return this.service.deleteAll(auth, dto); @@ -95,9 +99,10 @@ export class AssetController { @Get(':id') @Authenticated({ permission: Permission.AssetRead, sharedLink: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve an asset', description: 'Retrieve detailed information about a specific asset.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAssetInfo(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.get(auth, id) as Promise; @@ -106,9 +111,10 @@ export class AssetController { @Put('copy') @Authenticated({ permission: Permission.AssetCopy }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Copy asset', description: 'Copy asset information like albums, tags, etc. from one asset to another.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) copyAsset(@Auth() auth: AuthDto, @Body() dto: AssetCopyDto): Promise { return this.service.copy(auth, dto); @@ -116,9 +122,10 @@ export class AssetController { @Put(':id') @Authenticated({ permission: Permission.AssetUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Update an asset', description: 'Update information of a specific asset.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateAsset( @Auth() auth: AuthDto, @@ -130,9 +137,10 @@ export class AssetController { @Get(':id/metadata') @Authenticated({ permission: Permission.AssetRead }) - @ApiOperation({ + @Endpoint({ summary: 'Get asset metadata', description: 'Retrieve all metadata key-value pairs associated with the specified asset.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAssetMetadata(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.getMetadata(auth, id); @@ -140,9 +148,10 @@ export class AssetController { @Get(':id/ocr') @Authenticated({ permission: Permission.AssetRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve asset OCR data', description: 'Retrieve all OCR (Optical Character Recognition) data associated with the specified asset.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAssetOcr(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.getOcr(auth, id); @@ -150,9 +159,10 @@ export class AssetController { @Put(':id/metadata') @Authenticated({ permission: Permission.AssetUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Update asset metadata', description: 'Update or add metadata key-value pairs for the specified asset.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateAssetMetadata( @Auth() auth: AuthDto, @@ -164,9 +174,10 @@ export class AssetController { @Get(':id/metadata/:key') @Authenticated({ permission: Permission.AssetRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve asset metadata by key', description: 'Retrieve the value of a specific metadata key associated with the specified asset.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAssetMetadataByKey( @Auth() auth: AuthDto, @@ -178,9 +189,10 @@ export class AssetController { @Delete(':id/metadata/:key') @Authenticated({ permission: Permission.AssetUpdate }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete asset metadata by key', description: 'Delete a specific metadata key-value pair associated with the specified asset.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteAssetMetadata(@Auth() auth: AuthDto, @Param() { id, key }: AssetMetadataRouteParams): Promise { return this.service.deleteMetadataByKey(auth, id, key); diff --git a/server/src/controllers/auth-admin.controller.ts b/server/src/controllers/auth-admin.controller.ts index 8cbdf5d6da..d4cada9afc 100644 --- a/server/src/controllers/auth-admin.controller.ts +++ b/server/src/controllers/auth-admin.controller.ts @@ -1,5 +1,6 @@ import { Controller, HttpCode, HttpStatus, Post } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AuthDto } from 'src/dtos/auth.dto'; import { ApiTag, Permission } from 'src/enum'; import { Auth, Authenticated } from 'src/middleware/auth.guard'; @@ -12,9 +13,10 @@ export class AuthAdminController { @Post('unlink-all') @Authenticated({ permission: Permission.AdminAuthUnlinkAll, admin: true }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Unlink all OAuth accounts', description: 'Unlinks all OAuth accounts associated with user accounts in the system.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) unlinkAllOAuthAccountsAdmin(@Auth() auth: AuthDto): Promise { return this.service.unlinkAll(auth); diff --git a/server/src/controllers/auth.controller.ts b/server/src/controllers/auth.controller.ts index 7f76ff1952..ea09e33080 100644 --- a/server/src/controllers/auth.controller.ts +++ b/server/src/controllers/auth.controller.ts @@ -1,6 +1,7 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Post, Put, Req, Res } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; import { Request, Response } from 'express'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AuthDto, AuthStatusResponseDto, @@ -27,9 +28,10 @@ export class AuthController { constructor(private service: AuthService) {} @Post('login') - @ApiOperation({ + @Endpoint({ summary: 'Login', description: 'Login with username and password and receive a session token.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async login( @Res({ passthrough: true }) res: Response, @@ -48,18 +50,20 @@ export class AuthController { } @Post('admin-sign-up') - @ApiOperation({ + @Endpoint({ summary: 'Register admin', description: 'Create the first admin user in the system.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) signUpAdmin(@Body() dto: SignUpDto): Promise { return this.service.adminSignUp(dto); } @Post('validateToken') - @ApiOperation({ + @Endpoint({ summary: 'Validate access token', description: 'Validate the current authorization method is still valid.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) @Authenticated({ permission: false }) @HttpCode(HttpStatus.OK) @@ -70,9 +74,10 @@ export class AuthController { @Post('change-password') @Authenticated({ permission: Permission.AuthChangePassword }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Change password', description: 'Change the password of the current user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) changePassword(@Auth() auth: AuthDto, @Body() dto: ChangePasswordDto): Promise { return this.service.changePassword(auth, dto); @@ -81,9 +86,10 @@ export class AuthController { @Post('logout') @Authenticated() @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Logout', description: 'Logout the current user and invalidate the session token.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async logout( @Req() request: Request, @@ -102,7 +108,7 @@ export class AuthController { @Get('status') @Authenticated() - @ApiOperation({ + @Endpoint({ summary: 'Retrieve auth status', description: 'Get information about the current session, including whether the user has a password, and if the session can access locked assets.', @@ -114,9 +120,10 @@ export class AuthController { @Post('pin-code') @Authenticated({ permission: Permission.PinCodeCreate }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Setup pin code', description: 'Setup a new pin code for the current user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) setupPinCode(@Auth() auth: AuthDto, @Body() dto: PinCodeSetupDto): Promise { return this.service.setupPinCode(auth, dto); @@ -125,9 +132,10 @@ export class AuthController { @Put('pin-code') @Authenticated({ permission: Permission.PinCodeUpdate }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Change pin code', description: 'Change the pin code for the current user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async changePinCode(@Auth() auth: AuthDto, @Body() dto: PinCodeChangeDto): Promise { return this.service.changePinCode(auth, dto); @@ -136,9 +144,10 @@ export class AuthController { @Delete('pin-code') @Authenticated({ permission: Permission.PinCodeDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Reset pin code', description: 'Reset the pin code for the current user by providing the account password', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async resetPinCode(@Auth() auth: AuthDto, @Body() dto: PinCodeResetDto): Promise { return this.service.resetPinCode(auth, dto); @@ -147,9 +156,10 @@ export class AuthController { @Post('session/unlock') @Authenticated() @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Unlock auth session', description: 'Temporarily grant the session elevated access to locked assets by providing the correct PIN code.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async unlockAuthSession(@Auth() auth: AuthDto, @Body() dto: SessionUnlockDto): Promise { return this.service.unlockSession(auth, dto); @@ -157,9 +167,10 @@ export class AuthController { @Post('session/lock') @Authenticated() - @ApiOperation({ + @Endpoint({ summary: 'Lock auth session', description: 'Remove elevated access to locked assets from the current session.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) @HttpCode(HttpStatus.NO_CONTENT) async lockAuthSession(@Auth() auth: AuthDto): Promise { diff --git a/server/src/controllers/download.controller.ts b/server/src/controllers/download.controller.ts index 26288412d7..942d44f4c3 100644 --- a/server/src/controllers/download.controller.ts +++ b/server/src/controllers/download.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, HttpCode, HttpStatus, Post, StreamableFile } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AssetIdsDto } from 'src/dtos/asset.dto'; import { AuthDto } from 'src/dtos/auth.dto'; import { DownloadInfoDto, DownloadResponseDto } from 'src/dtos/download.dto'; @@ -15,10 +16,11 @@ export class DownloadController { @Post('info') @Authenticated({ permission: Permission.AssetDownload, sharedLink: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve download information', description: 'Retrieve information about how to request a download for the specified assets or album. The response includes groups of assets that can be downloaded together.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getDownloadInfo(@Auth() auth: AuthDto, @Body() dto: DownloadInfoDto): Promise { return this.service.getDownloadInfo(auth, dto); @@ -28,10 +30,11 @@ export class DownloadController { @Authenticated({ permission: Permission.AssetDownload, sharedLink: true }) @FileResponse() @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Download asset archive', description: 'Download a ZIP archive containing the specified assets. The assets must have been previously requested via the "getDownloadInfo" endpoint.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) downloadArchive(@Auth() auth: AuthDto, @Body() dto: AssetIdsDto): Promise { return this.service.downloadArchive(auth, dto).then(asStreamableFile); diff --git a/server/src/controllers/duplicate.controller.ts b/server/src/controllers/duplicate.controller.ts index 5fddef9dd0..e8c8e5ef80 100644 --- a/server/src/controllers/duplicate.controller.ts +++ b/server/src/controllers/duplicate.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { BulkIdsDto } from 'src/dtos/asset-ids.response.dto'; import { AuthDto } from 'src/dtos/auth.dto'; import { DuplicateResponseDto } from 'src/dtos/duplicate.dto'; @@ -15,9 +16,10 @@ export class DuplicateController { @Get() @Authenticated({ permission: Permission.DuplicateRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve duplicates', description: 'Retrieve a list of duplicate assets available to the authenticated user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAssetDuplicates(@Auth() auth: AuthDto): Promise { return this.service.getDuplicates(auth); @@ -26,9 +28,10 @@ export class DuplicateController { @Delete() @Authenticated({ permission: Permission.DuplicateDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete duplicates', description: 'Delete multiple duplicate assets specified by their IDs.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteDuplicates(@Auth() auth: AuthDto, @Body() dto: BulkIdsDto): Promise { return this.service.deleteAll(auth, dto); @@ -37,9 +40,10 @@ export class DuplicateController { @Delete(':id') @Authenticated({ permission: Permission.DuplicateDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete a duplicate', description: 'Delete a single duplicate asset specified by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteDuplicate(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.delete(auth, id); diff --git a/server/src/controllers/face.controller.ts b/server/src/controllers/face.controller.ts index cc7f23929a..a1c1d6ee4d 100644 --- a/server/src/controllers/face.controller.ts +++ b/server/src/controllers/face.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put, Query } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AuthDto } from 'src/dtos/auth.dto'; import { AssetFaceCreateDto, @@ -20,10 +21,11 @@ export class FaceController { @Post() @Authenticated({ permission: Permission.FaceCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Create a face', description: 'Create a new face that has not been discovered by facial recognition. The content of the bounding box is considered a face.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createFace(@Auth() auth: AuthDto, @Body() dto: AssetFaceCreateDto) { return this.service.createFace(auth, dto); @@ -31,9 +33,10 @@ export class FaceController { @Get() @Authenticated({ permission: Permission.FaceRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve faces for asset', description: 'Retrieve all faces belonging to an asset.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getFaces(@Auth() auth: AuthDto, @Query() dto: FaceDto): Promise { return this.service.getFacesById(auth, dto); @@ -41,9 +44,10 @@ export class FaceController { @Put(':id') @Authenticated({ permission: Permission.FaceUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Re-assign a face to another person', description: 'Re-assign the face provided in the body to the person identified by the id in the path parameter.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) reassignFacesById( @Auth() auth: AuthDto, @@ -56,9 +60,10 @@ export class FaceController { @Delete(':id') @Authenticated({ permission: Permission.FaceDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete a face', description: 'Delete a face identified by the id. Optionally can be force deleted.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteFace(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto, @Body() dto: AssetFaceDeleteDto): Promise { return this.service.deleteFace(auth, id, dto); diff --git a/server/src/controllers/job.controller.ts b/server/src/controllers/job.controller.ts index b34f5ffecf..34c6bdc27f 100644 --- a/server/src/controllers/job.controller.ts +++ b/server/src/controllers/job.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Get, HttpCode, HttpStatus, Param, Post, Put } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AllJobStatusResponseDto, JobCommandDto, JobCreateDto, JobIdParamDto, JobStatusDto } from 'src/dtos/job.dto'; import { ApiTag, Permission } from 'src/enum'; import { Authenticated } from 'src/middleware/auth.guard'; @@ -12,9 +13,10 @@ export class JobController { @Get() @Authenticated({ permission: Permission.JobRead, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve queue counts and status', description: 'Retrieve the counts of the current queue, as well as the current status.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAllJobsStatus(): Promise { return this.service.getAllJobsStatus(); @@ -23,10 +25,11 @@ export class JobController { @Post() @Authenticated({ permission: Permission.JobCreate, admin: true }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Create a manual job', description: 'Run a specific job. Most jobs are queued automatically, but this endpoint allows for manual creation of a handful of jobs, including various cleanup tasks, as well as creating a new database backup.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createJob(@Body() dto: JobCreateDto): Promise { return this.service.create(dto); @@ -34,10 +37,11 @@ export class JobController { @Put(':id') @Authenticated({ permission: Permission.JobCreate, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Run jobs', description: 'Queue all assets for a specific job type. Defaults to only queueing assets that have not yet been processed, but the force command can be used to re-process all assets.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) sendJobCommand(@Param() { id }: JobIdParamDto, @Body() dto: JobCommandDto): Promise { return this.service.handleCommand(id, dto); diff --git a/server/src/controllers/library.controller.ts b/server/src/controllers/library.controller.ts index 8b527eb4bb..5672e9117a 100644 --- a/server/src/controllers/library.controller.ts +++ b/server/src/controllers/library.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { CreateLibraryDto, LibraryResponseDto, @@ -20,9 +21,10 @@ export class LibraryController { @Get() @Authenticated({ permission: Permission.LibraryRead, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve libraries', description: 'Retrieve a list of external libraries.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAllLibraries(): Promise { return this.service.getAll(); @@ -30,9 +32,10 @@ export class LibraryController { @Post() @Authenticated({ permission: Permission.LibraryCreate, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Create a library', description: 'Create a new external library.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createLibrary(@Body() dto: CreateLibraryDto): Promise { return this.service.create(dto); @@ -40,9 +43,10 @@ export class LibraryController { @Get(':id') @Authenticated({ permission: Permission.LibraryRead, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve a library', description: 'Retrieve an external library by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getLibrary(@Param() { id }: UUIDParamDto): Promise { return this.service.get(id); @@ -50,9 +54,10 @@ export class LibraryController { @Put(':id') @Authenticated({ permission: Permission.LibraryUpdate, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Update a library', description: 'Update an existing external library.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateLibrary(@Param() { id }: UUIDParamDto, @Body() dto: UpdateLibraryDto): Promise { return this.service.update(id, dto); @@ -61,9 +66,10 @@ export class LibraryController { @Delete(':id') @Authenticated({ permission: Permission.LibraryDelete, admin: true }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete a library', description: 'Delete an external library by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteLibrary(@Param() { id }: UUIDParamDto): Promise { return this.service.delete(id); @@ -72,9 +78,10 @@ export class LibraryController { @Post(':id/validate') @Authenticated({ admin: true }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Validate library settings', description: 'Validate the settings of an external library.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) // TODO: change endpoint to validate current settings instead validate(@Param() { id }: UUIDParamDto, @Body() dto: ValidateLibraryDto): Promise { @@ -83,10 +90,11 @@ export class LibraryController { @Get(':id/statistics') @Authenticated({ permission: Permission.LibraryStatistics, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve library statistics', description: 'Retrieve statistics for a specific external library, including number of videos, images, and storage usage.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getLibraryStatistics(@Param() { id }: UUIDParamDto): Promise { return this.service.getStatistics(id); @@ -95,9 +103,10 @@ export class LibraryController { @Post(':id/scan') @Authenticated({ permission: Permission.LibraryUpdate, admin: true }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Scan a library', description: 'Queue a scan for the external library to find and import new assets.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) scanLibrary(@Param() { id }: UUIDParamDto): Promise { return this.service.queueScan(id); diff --git a/server/src/controllers/map.controller.ts b/server/src/controllers/map.controller.ts index 41acfbd5b4..dbd1082561 100644 --- a/server/src/controllers/map.controller.ts +++ b/server/src/controllers/map.controller.ts @@ -1,5 +1,6 @@ import { Controller, Get, HttpCode, HttpStatus, Query } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AuthDto } from 'src/dtos/auth.dto'; import { MapMarkerDto, @@ -18,9 +19,10 @@ export class MapController { @Get('markers') @Authenticated() - @ApiOperation({ + @Endpoint({ summary: 'Retrieve map markers', description: 'Retrieve a list of latitude and longitude coordinates for every asset with location data.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getMapMarkers(@Auth() auth: AuthDto, @Query() options: MapMarkerDto): Promise { return this.service.getMapMarkers(auth, options); @@ -29,9 +31,10 @@ export class MapController { @Authenticated() @Get('reverse-geocode') @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Reverse geocode coordinates', description: 'Retrieve location information (e.g., city, country) for given latitude and longitude coordinates.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) reverseGeocode(@Query() dto: MapReverseGeocodeDto): Promise { return this.service.reverseGeocode(dto); diff --git a/server/src/controllers/memory.controller.ts b/server/src/controllers/memory.controller.ts index d433ae88ed..cbf86199bb 100644 --- a/server/src/controllers/memory.controller.ts +++ b/server/src/controllers/memory.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put, Query } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { BulkIdResponseDto, BulkIdsDto } from 'src/dtos/asset-ids.response.dto'; import { AuthDto } from 'src/dtos/auth.dto'; import { @@ -21,10 +22,11 @@ export class MemoryController { @Get() @Authenticated({ permission: Permission.MemoryRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve memories', description: 'Retrieve a list of memories. Memories are sorted descending by creation date by default, although they can also be sorted in ascending order, or randomly.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) searchMemories(@Auth() auth: AuthDto, @Query() dto: MemorySearchDto): Promise { return this.service.search(auth, dto); @@ -32,10 +34,11 @@ export class MemoryController { @Post() @Authenticated({ permission: Permission.MemoryCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Create a memory', description: 'Create a new memory by providing a name, description, and a list of asset IDs to include in the memory.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createMemory(@Auth() auth: AuthDto, @Body() dto: MemoryCreateDto): Promise { return this.service.create(auth, dto); @@ -43,9 +46,10 @@ export class MemoryController { @Get('statistics') @Authenticated({ permission: Permission.MemoryStatistics }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve memories statistics', description: 'Retrieve statistics about memories, such as total count and other relevant metrics.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) memoriesStatistics(@Auth() auth: AuthDto, @Query() dto: MemorySearchDto): Promise { return this.service.statistics(auth, dto); @@ -53,9 +57,10 @@ export class MemoryController { @Get(':id') @Authenticated({ permission: Permission.MemoryRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve a memory', description: 'Retrieve a specific memory by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getMemory(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.get(auth, id); @@ -63,9 +68,10 @@ export class MemoryController { @Put(':id') @Authenticated({ permission: Permission.MemoryUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Update a memory', description: 'Update an existing memory by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateMemory( @Auth() auth: AuthDto, @@ -78,9 +84,10 @@ export class MemoryController { @Delete(':id') @Authenticated({ permission: Permission.MemoryDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete a memory', description: 'Delete a specific memory by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteMemory(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.remove(auth, id); @@ -88,9 +95,10 @@ export class MemoryController { @Put(':id/assets') @Authenticated({ permission: Permission.MemoryAssetCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Add assets to a memory', description: 'Add a list of asset IDs to a specific memory.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) addMemoryAssets( @Auth() auth: AuthDto, @@ -103,9 +111,10 @@ export class MemoryController { @Delete(':id/assets') @Authenticated({ permission: Permission.MemoryAssetDelete }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Remove assets from a memory', description: 'Remove a list of asset IDs from a specific memory.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) removeMemoryAssets( @Auth() auth: AuthDto, diff --git a/server/src/controllers/notification-admin.controller.ts b/server/src/controllers/notification-admin.controller.ts index fe7d9d1e49..c322c5a2b6 100644 --- a/server/src/controllers/notification-admin.controller.ts +++ b/server/src/controllers/notification-admin.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, HttpCode, HttpStatus, Param, Post } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AuthDto } from 'src/dtos/auth.dto'; import { NotificationCreateDto, @@ -21,9 +22,10 @@ export class NotificationAdminController { @Post() @Authenticated({ admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Create a notification', description: 'Create a new notification for a specific user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createNotification(@Auth() auth: AuthDto, @Body() dto: NotificationCreateDto): Promise { return this.service.create(auth, dto); @@ -32,9 +34,10 @@ export class NotificationAdminController { @Post('test-email') @Authenticated({ admin: true }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Send test email', description: 'Send a test email using the provided SMTP configuration.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) sendTestEmailAdmin(@Auth() auth: AuthDto, @Body() dto: SystemConfigSmtpDto): Promise { return this.service.sendTestEmail(auth.user.id, dto); @@ -43,9 +46,10 @@ export class NotificationAdminController { @Post('templates/:name') @Authenticated({ admin: true }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Render email template', description: 'Retrieve a preview of the provided email template.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getNotificationTemplateAdmin( @Auth() auth: AuthDto, diff --git a/server/src/controllers/notification.controller.ts b/server/src/controllers/notification.controller.ts index 7d4840dd0b..0a28e1bda8 100644 --- a/server/src/controllers/notification.controller.ts +++ b/server/src/controllers/notification.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Put, Query } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AuthDto } from 'src/dtos/auth.dto'; import { NotificationDeleteAllDto, @@ -20,9 +21,10 @@ export class NotificationController { @Get() @Authenticated({ permission: Permission.NotificationRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve notifications', description: 'Retrieve a list of notifications.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getNotifications(@Auth() auth: AuthDto, @Query() dto: NotificationSearchDto): Promise { return this.service.search(auth, dto); @@ -31,9 +33,10 @@ export class NotificationController { @Put() @Authenticated({ permission: Permission.NotificationUpdate }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Update notifications', description: 'Update a list of notifications. Allows to bulk-set the read status of notifications.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateNotifications(@Auth() auth: AuthDto, @Body() dto: NotificationUpdateAllDto): Promise { return this.service.updateAll(auth, dto); @@ -42,9 +45,10 @@ export class NotificationController { @Delete() @Authenticated({ permission: Permission.NotificationDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete notifications', description: 'Delete a list of notifications at once.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteNotifications(@Auth() auth: AuthDto, @Body() dto: NotificationDeleteAllDto): Promise { return this.service.deleteAll(auth, dto); @@ -52,9 +56,10 @@ export class NotificationController { @Get(':id') @Authenticated({ permission: Permission.NotificationRead }) - @ApiOperation({ + @Endpoint({ summary: 'Get a notification', description: 'Retrieve a specific notification identified by id.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getNotification(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.get(auth, id); @@ -62,9 +67,10 @@ export class NotificationController { @Put(':id') @Authenticated({ permission: Permission.NotificationUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Update a notification', description: 'Update a specific notification to set its read status.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateNotification( @Auth() auth: AuthDto, @@ -77,9 +83,10 @@ export class NotificationController { @Delete(':id') @Authenticated({ permission: Permission.NotificationDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete a notification', description: 'Delete a specific notification.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteNotification(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.delete(auth, id); diff --git a/server/src/controllers/oauth.controller.ts b/server/src/controllers/oauth.controller.ts index cd15486d56..797bf497ef 100644 --- a/server/src/controllers/oauth.controller.ts +++ b/server/src/controllers/oauth.controller.ts @@ -1,6 +1,7 @@ import { Body, Controller, Get, HttpCode, HttpStatus, Post, Redirect, Req, Res } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; import { Request, Response } from 'express'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AuthDto, LoginResponseDto, @@ -21,10 +22,11 @@ export class OAuthController { @Get('mobile-redirect') @Redirect() - @ApiOperation({ + @Endpoint({ summary: 'Redirect OAuth to mobile', description: 'Requests to this URL are automatically forwarded to the mobile app, and is used in some cases for OAuth redirecting.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) redirectOAuthToMobile(@Req() request: Request) { return { @@ -34,9 +36,10 @@ export class OAuthController { } @Post('authorize') - @ApiOperation({ + @Endpoint({ summary: 'Start OAuth', description: 'Initiate the OAuth authorization process.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async startOAuth( @Body() dto: OAuthConfigDto, @@ -58,9 +61,10 @@ export class OAuthController { } @Post('callback') - @ApiOperation({ + @Endpoint({ summary: 'Finish OAuth', description: 'Complete the OAuth authorization process by exchanging the authorization code for a session token.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async finishOAuth( @Req() request: Request, @@ -84,9 +88,10 @@ export class OAuthController { @Post('link') @Authenticated() @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Link OAuth account', description: 'Link an OAuth account to the authenticated user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) linkOAuthAccount( @Req() request: Request, @@ -99,9 +104,10 @@ export class OAuthController { @Post('unlink') @Authenticated() @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Unlink OAuth account', description: 'Unlink the OAuth account from the authenticated user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) unlinkOAuthAccount(@Auth() auth: AuthDto): Promise { return this.service.unlink(auth); diff --git a/server/src/controllers/partner.controller.ts b/server/src/controllers/partner.controller.ts index 63ad84002f..951aee7e0c 100644 --- a/server/src/controllers/partner.controller.ts +++ b/server/src/controllers/partner.controller.ts @@ -1,6 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put, Query } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; -import { EndpointLifecycle } from 'src/decorators'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AuthDto } from 'src/dtos/auth.dto'; import { PartnerCreateDto, PartnerResponseDto, PartnerSearchDto, PartnerUpdateDto } from 'src/dtos/partner.dto'; import { ApiTag, Permission } from 'src/enum'; @@ -15,9 +15,10 @@ export class PartnerController { @Get() @Authenticated({ permission: Permission.PartnerRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve partners', description: 'Retrieve a list of partners with whom assets are shared.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getPartners(@Auth() auth: AuthDto, @Query() dto: PartnerSearchDto): Promise { return this.service.search(auth, dto); @@ -25,19 +26,20 @@ export class PartnerController { @Post() @Authenticated({ permission: Permission.PartnerCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Create a partner', description: 'Create a new partner to share assets with.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createPartner(@Auth() auth: AuthDto, @Body() dto: PartnerCreateDto): Promise { return this.service.create(auth, dto); } @Post(':id') - @EndpointLifecycle({ - deprecatedAt: 'v1.141.0', + @Endpoint({ summary: 'Create a partner', description: 'Create a new partner to share assets with.', + history: new HistoryBuilder().added('v1').deprecated('v1', { replacementId: 'createPartner' }), }) @Authenticated({ permission: Permission.PartnerCreate }) createPartnerDeprecated(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { @@ -46,9 +48,10 @@ export class PartnerController { @Put(':id') @Authenticated({ permission: Permission.PartnerUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Update a partner', description: "Specify whether a partner's assets should appear in the user's timeline.", + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updatePartner( @Auth() auth: AuthDto, @@ -61,9 +64,10 @@ export class PartnerController { @Delete(':id') @Authenticated({ permission: Permission.PartnerDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Remove a partner', description: 'Stop sharing assets with a partner.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) removePartner(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.remove(auth, id); diff --git a/server/src/controllers/person.controller.ts b/server/src/controllers/person.controller.ts index 6acb958444..5abd6eb1b4 100644 --- a/server/src/controllers/person.controller.ts +++ b/server/src/controllers/person.controller.ts @@ -12,8 +12,9 @@ import { Query, Res, } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; import { NextFunction, Response } from 'express'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { BulkIdResponseDto, BulkIdsDto } from 'src/dtos/asset-ids.response.dto'; import { AuthDto } from 'src/dtos/auth.dto'; import { @@ -46,16 +47,21 @@ export class PersonController { @Get() @Authenticated({ permission: Permission.PersonRead }) - @ApiOperation({ summary: 'Get all people', description: 'Retrieve a list of all people.' }) + @Endpoint({ + summary: 'Get all people', + description: 'Retrieve a list of all people.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) getAllPeople(@Auth() auth: AuthDto, @Query() options: PersonSearchDto): Promise { return this.service.getAll(auth, options); } @Post() @Authenticated({ permission: Permission.PersonCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Create a person', description: 'Create a new person that can have multiple faces assigned to them.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createPerson(@Auth() auth: AuthDto, @Body() dto: PersonCreateDto): Promise { return this.service.create(auth, dto); @@ -63,7 +69,11 @@ export class PersonController { @Put() @Authenticated({ permission: Permission.PersonUpdate }) - @ApiOperation({ summary: 'Update people', description: 'Bulk update multiple people at once.' }) + @Endpoint({ + summary: 'Update people', + description: 'Bulk update multiple people at once.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) updatePeople(@Auth() auth: AuthDto, @Body() dto: PeopleUpdateDto): Promise { return this.service.updateAll(auth, dto); } @@ -71,21 +81,33 @@ export class PersonController { @Delete() @Authenticated({ permission: Permission.PersonDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ summary: 'Delete people', description: 'Bulk delete a list of people at once.' }) + @Endpoint({ + summary: 'Delete people', + description: 'Bulk delete a list of people at once.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) deletePeople(@Auth() auth: AuthDto, @Body() dto: BulkIdsDto): Promise { return this.service.deleteAll(auth, dto); } @Get(':id') @Authenticated({ permission: Permission.PersonRead }) - @ApiOperation({ summary: 'Get a person', description: 'Retrieve a person by id.' }) + @Endpoint({ + summary: 'Get a person', + description: 'Retrieve a person by id.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) getPerson(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.getById(auth, id); } @Put(':id') @Authenticated({ permission: Permission.PersonUpdate }) - @ApiOperation({ summary: 'Update person', description: 'Update an individual person.' }) + @Endpoint({ + summary: 'Update person', + description: 'Update an individual person.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) updatePerson( @Auth() auth: AuthDto, @Param() { id }: UUIDParamDto, @@ -97,14 +119,22 @@ export class PersonController { @Delete(':id') @Authenticated({ permission: Permission.PersonDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ summary: 'Delete person', description: 'Delete an individual person.' }) + @Endpoint({ + summary: 'Delete person', + description: 'Delete an individual person.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) deletePerson(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.delete(auth, id); } @Get(':id/statistics') @Authenticated({ permission: Permission.PersonStatistics }) - @ApiOperation({ summary: 'Get person statistics', description: 'Retrieve statistics about a specific person.' }) + @Endpoint({ + summary: 'Get person statistics', + description: 'Retrieve statistics about a specific person.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) getPersonStatistics(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.getStatistics(auth, id); } @@ -112,7 +142,11 @@ export class PersonController { @Get(':id/thumbnail') @FileResponse() @Authenticated({ permission: Permission.PersonRead }) - @ApiOperation({ summary: 'Get person thumbnail', description: 'Retrieve the thumbnail file for a person.' }) + @Endpoint({ + summary: 'Get person thumbnail', + description: 'Retrieve the thumbnail file for a person.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) async getPersonThumbnail( @Res() res: Response, @Next() next: NextFunction, @@ -124,7 +158,11 @@ export class PersonController { @Put(':id/reassign') @Authenticated({ permission: Permission.PersonReassign }) - @ApiOperation({ summary: 'Reassign faces', description: 'Bulk reassign a list of faces to a different person.' }) + @Endpoint({ + summary: 'Reassign faces', + description: 'Bulk reassign a list of faces to a different person.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) reassignFaces( @Auth() auth: AuthDto, @Param() { id }: UUIDParamDto, @@ -136,9 +174,10 @@ export class PersonController { @Post(':id/merge') @Authenticated({ permission: Permission.PersonMerge }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Merge people', description: 'Merge a list of people into the person specified in the path parameter.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) mergePerson( @Auth() auth: AuthDto, diff --git a/server/src/controllers/search.controller.ts b/server/src/controllers/search.controller.ts index e04fbaa3f6..439a7a5118 100644 --- a/server/src/controllers/search.controller.ts +++ b/server/src/controllers/search.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Get, HttpCode, HttpStatus, Post, Query } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AssetResponseDto } from 'src/dtos/asset-response.dto'; import { AuthDto } from 'src/dtos/auth.dto'; import { PersonResponseDto } from 'src/dtos/person.dto'; @@ -29,9 +30,10 @@ export class SearchController { @Post('metadata') @Authenticated({ permission: Permission.AssetRead }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Search assets by metadata', description: 'Search for assets based on various metadata criteria.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) searchAssets(@Auth() auth: AuthDto, @Body() dto: MetadataSearchDto): Promise { return this.service.searchMetadata(auth, dto); @@ -40,9 +42,10 @@ export class SearchController { @Post('statistics') @Authenticated({ permission: Permission.AssetStatistics }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Search asset statistics', description: 'Retrieve statistical data about assets based on search criteria, such as the total matching count.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) searchAssetStatistics(@Auth() auth: AuthDto, @Body() dto: StatisticsSearchDto): Promise { return this.service.searchStatistics(auth, dto); @@ -51,9 +54,10 @@ export class SearchController { @Post('random') @Authenticated({ permission: Permission.AssetRead }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Search random assets', description: 'Retrieve a random selection of assets based on the provided criteria.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) searchRandom(@Auth() auth: AuthDto, @Body() dto: RandomSearchDto): Promise { return this.service.searchRandom(auth, dto); @@ -62,9 +66,10 @@ export class SearchController { @Post('large-assets') @Authenticated({ permission: Permission.AssetRead }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Search large assets', description: 'Search for assets that are considered large based on specified criteria.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) searchLargeAssets(@Auth() auth: AuthDto, @Query() dto: LargeAssetSearchDto): Promise { return this.service.searchLargeAssets(auth, dto); @@ -73,9 +78,10 @@ export class SearchController { @Post('smart') @Authenticated({ permission: Permission.AssetRead }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Smart asset search', description: 'Perform a smart search for assets by using machine learning vectors to determine relevance.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) searchSmart(@Auth() auth: AuthDto, @Body() dto: SmartSearchDto): Promise { return this.service.searchSmart(auth, dto); @@ -83,9 +89,10 @@ export class SearchController { @Get('explore') @Authenticated({ permission: Permission.AssetRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve explore data', description: 'Retrieve data for the explore section, such as popular people and places.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getExploreData(@Auth() auth: AuthDto): Promise { return this.service.getExploreData(auth); @@ -93,9 +100,10 @@ export class SearchController { @Get('person') @Authenticated({ permission: Permission.PersonRead }) - @ApiOperation({ + @Endpoint({ summary: 'Search people', description: 'Search for people by name.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) searchPerson(@Auth() auth: AuthDto, @Query() dto: SearchPeopleDto): Promise { return this.service.searchPerson(auth, dto); @@ -103,9 +111,10 @@ export class SearchController { @Get('places') @Authenticated({ permission: Permission.AssetRead }) - @ApiOperation({ + @Endpoint({ summary: 'Search places', description: 'Search for places by name.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) searchPlaces(@Query() dto: SearchPlacesDto): Promise { return this.service.searchPlaces(dto); @@ -113,10 +122,11 @@ export class SearchController { @Get('cities') @Authenticated({ permission: Permission.AssetRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve assets by city', description: 'Retrieve a list of assets with each asset belonging to a different city. This endpoint is used on the places pages to show a single thumbnail for each city the user has assets in.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAssetsByCity(@Auth() auth: AuthDto): Promise { return this.service.getAssetsByCity(auth); @@ -124,10 +134,11 @@ export class SearchController { @Get('suggestions') @Authenticated({ permission: Permission.AssetRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve search suggestions', description: 'Retrieve search suggestions based on partial input. This endpoint is used for typeahead search features.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getSearchSuggestions(@Auth() auth: AuthDto, @Query() dto: SearchSuggestionRequestDto): Promise { // TODO fix open api generation to indicate that results can be nullable diff --git a/server/src/controllers/server.controller.ts b/server/src/controllers/server.controller.ts index c9c8539bb3..ffcb50c674 100644 --- a/server/src/controllers/server.controller.ts +++ b/server/src/controllers/server.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Put } from '@nestjs/common'; -import { ApiNotFoundResponse, ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiNotFoundResponse, ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { LicenseKeyDto, LicenseResponseDto } from 'src/dtos/license.dto'; import { ServerAboutResponseDto, @@ -32,84 +33,113 @@ export class ServerController { @Get('about') @Authenticated({ permission: Permission.ServerAbout }) - @ApiOperation({ summary: 'Get server information', description: 'Retrieve a list of information about the server.' }) + @Endpoint({ + summary: 'Get server information', + description: 'Retrieve a list of information about the server.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) getAboutInfo(): Promise { return this.service.getAboutInfo(); } @Get('apk-links') @Authenticated({ permission: Permission.ServerApkLinks }) - @ApiOperation({ summary: 'Get APK links', description: 'Retrieve links to the APKs for the current server version.' }) + @Endpoint({ + summary: 'Get APK links', + description: 'Retrieve links to the APKs for the current server version.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) getApkLinks(): ServerApkLinksDto { return this.service.getApkLinks(); } @Get('storage') @Authenticated({ permission: Permission.ServerStorage }) - @ApiOperation({ + @Endpoint({ summary: 'Get storage', description: 'Retrieve the current storage utilization information of the server.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getStorage(): Promise { return this.service.getStorage(); } @Get('ping') - @ApiOperation({ summary: 'Ping', description: 'Pong' }) + @Endpoint({ + summary: 'Ping', + description: 'Pong', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) pingServer(): ServerPingResponse { return this.service.ping(); } @Get('version') - @ApiOperation({ + @Endpoint({ summary: 'Get server version', description: 'Retrieve the current server version in semantic versioning (semver) format.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getServerVersion(): ServerVersionResponseDto { return this.versionService.getVersion(); } @Get('version-history') - @ApiOperation({ + @Endpoint({ summary: 'Get version history', description: 'Retrieve a list of past versions the server has been on.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getVersionHistory(): Promise { return this.versionService.getVersionHistory(); } @Get('features') - @ApiOperation({ summary: 'Get features', description: 'Retrieve available features supported by this server.' }) + @Endpoint({ + summary: 'Get features', + description: 'Retrieve available features supported by this server.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) getServerFeatures(): Promise { return this.service.getFeatures(); } @Get('theme') - @ApiOperation({ summary: 'Get theme', description: 'Retrieve the custom CSS, if existent.' }) + @Endpoint({ + summary: 'Get theme', + description: 'Retrieve the custom CSS, if existent.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) getTheme(): Promise { return this.service.getTheme(); } @Get('config') - @ApiOperation({ summary: 'Get config', description: 'Retrieve the current server configuration.' }) + @Endpoint({ + summary: 'Get config', + description: 'Retrieve the current server configuration.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) getServerConfig(): Promise { return this.service.getSystemConfig(); } @Get('statistics') @Authenticated({ permission: Permission.ServerStatistics, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Get statistics', description: 'Retrieve statistics about the entire Immich instance such as asset counts.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getServerStatistics(): Promise { return this.service.getStatistics(); } @Get('media-types') - @ApiOperation({ + @Endpoint({ summary: 'Get supported media types', description: 'Retrieve all media types supported by the server.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getSupportedMediaTypes(): ServerMediaTypesResponseDto { return this.service.getSupportedMediaTypes(); @@ -118,9 +148,10 @@ export class ServerController { @Get('license') @Authenticated({ permission: Permission.ServerLicenseRead, admin: true }) @ApiNotFoundResponse() - @ApiOperation({ + @Endpoint({ summary: 'Get product key', description: 'Retrieve information about whether the server currently has a product key registered.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getServerLicense(): Promise { return this.service.getLicense(); @@ -128,9 +159,10 @@ export class ServerController { @Put('license') @Authenticated({ permission: Permission.ServerLicenseUpdate, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Set server product key', description: 'Validate and set the server product key if successful.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) setServerLicense(@Body() license: LicenseKeyDto): Promise { return this.service.setLicense(license); @@ -139,16 +171,21 @@ export class ServerController { @Delete('license') @Authenticated({ permission: Permission.ServerLicenseDelete, admin: true }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ summary: 'Delete server product key', description: 'Delete the currently set server product key.' }) + @Endpoint({ + summary: 'Delete server product key', + description: 'Delete the currently set server product key.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) deleteServerLicense(): Promise { return this.service.deleteLicense(); } @Get('version-check') @Authenticated({ permission: Permission.ServerVersionCheck }) - @ApiOperation({ + @Endpoint({ summary: 'Get version check status', description: 'Retrieve information about the last time the version check ran.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getVersionCheck(): Promise { return this.systemMetadataService.getVersionCheckState(); diff --git a/server/src/controllers/session.controller.ts b/server/src/controllers/session.controller.ts index 47cd7a6f19..d21cca3a83 100644 --- a/server/src/controllers/session.controller.ts +++ b/server/src/controllers/session.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AuthDto } from 'src/dtos/auth.dto'; import { SessionCreateDto, SessionCreateResponseDto, SessionResponseDto, SessionUpdateDto } from 'src/dtos/session.dto'; import { ApiTag, Permission } from 'src/enum'; @@ -14,9 +15,10 @@ export class SessionController { @Post() @Authenticated({ permission: Permission.SessionCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Create a session', description: 'Create a session as a child to the current session. This endpoint is used for casting.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createSession(@Auth() auth: AuthDto, @Body() dto: SessionCreateDto): Promise { return this.service.create(auth, dto); @@ -24,9 +26,10 @@ export class SessionController { @Get() @Authenticated({ permission: Permission.SessionRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve sessions', description: 'Retrieve a list of sessions for the user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getSessions(@Auth() auth: AuthDto): Promise { return this.service.getAll(auth); @@ -35,9 +38,10 @@ export class SessionController { @Delete() @Authenticated({ permission: Permission.SessionDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete all sessions', description: 'Delete all sessions for the user. This will not delete the current session.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteAllSessions(@Auth() auth: AuthDto): Promise { return this.service.deleteAll(auth); @@ -45,9 +49,10 @@ export class SessionController { @Put(':id') @Authenticated({ permission: Permission.SessionUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Update a session', description: 'Update a specific session identified by id.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateSession( @Auth() auth: AuthDto, @@ -60,9 +65,10 @@ export class SessionController { @Delete(':id') @Authenticated({ permission: Permission.SessionDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete a session', description: 'Delete a specific session by id.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteSession(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.delete(auth, id); @@ -71,9 +77,10 @@ export class SessionController { @Post(':id/lock') @Authenticated({ permission: Permission.SessionLock }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Lock a session', description: 'Lock a specific session by id.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) lockSession(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.lock(auth, id); diff --git a/server/src/controllers/shared-link.controller.ts b/server/src/controllers/shared-link.controller.ts index e3e55f2941..8875127a25 100644 --- a/server/src/controllers/shared-link.controller.ts +++ b/server/src/controllers/shared-link.controller.ts @@ -13,8 +13,9 @@ import { Req, Res, } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; import { Request, Response } from 'express'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AssetIdsResponseDto } from 'src/dtos/asset-ids.response.dto'; import { AssetIdsDto } from 'src/dtos/asset.dto'; import { AuthDto } from 'src/dtos/auth.dto'; @@ -39,9 +40,10 @@ export class SharedLinkController { @Get() @Authenticated({ permission: Permission.SharedLinkRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve all shared links', description: 'Retrieve a list of all shared links.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAllSharedLinks(@Auth() auth: AuthDto, @Query() dto: SharedLinkSearchDto): Promise { return this.service.getAll(auth, dto); @@ -49,9 +51,10 @@ export class SharedLinkController { @Get('me') @Authenticated({ sharedLink: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve current shared link', description: 'Retrieve the current shared link associated with authentication method.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async getMySharedLink( @Auth() auth: AuthDto, @@ -73,9 +76,10 @@ export class SharedLinkController { @Get(':id') @Authenticated({ permission: Permission.SharedLinkRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve a shared link', description: 'Retrieve a specific shared link by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getSharedLinkById(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.get(auth, id); @@ -83,9 +87,10 @@ export class SharedLinkController { @Post() @Authenticated({ permission: Permission.SharedLinkCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Create a shared link', description: 'Create a new shared link.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createSharedLink(@Auth() auth: AuthDto, @Body() dto: SharedLinkCreateDto) { return this.service.create(auth, dto); @@ -93,9 +98,10 @@ export class SharedLinkController { @Patch(':id') @Authenticated({ permission: Permission.SharedLinkUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Update a shared link', description: 'Update an existing shared link by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateSharedLink( @Auth() auth: AuthDto, @@ -108,9 +114,10 @@ export class SharedLinkController { @Delete(':id') @Authenticated({ permission: Permission.SharedLinkDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete a shared link', description: 'Delete a specific shared link by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) removeSharedLink(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.remove(auth, id); @@ -118,10 +125,11 @@ export class SharedLinkController { @Put(':id/assets') @Authenticated({ sharedLink: true }) - @ApiOperation({ + @Endpoint({ summary: 'Add assets to a shared link', description: 'Add assets to a specific shared link by its ID. This endpoint is only relevant for shared link of type individual.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) addSharedLinkAssets( @Auth() auth: AuthDto, @@ -133,10 +141,11 @@ export class SharedLinkController { @Delete(':id/assets') @Authenticated({ sharedLink: true }) - @ApiOperation({ + @Endpoint({ summary: 'Remove assets from a shared link', description: 'Remove assets from a specific shared link by its ID. This endpoint is only relevant for shared link of type individual.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) removeSharedLinkAssets( @Auth() auth: AuthDto, diff --git a/server/src/controllers/stack.controller.ts b/server/src/controllers/stack.controller.ts index def3900c71..b35b49c786 100644 --- a/server/src/controllers/stack.controller.ts +++ b/server/src/controllers/stack.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put, Query } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { BulkIdsDto } from 'src/dtos/asset-ids.response.dto'; import { AuthDto } from 'src/dtos/auth.dto'; import { StackCreateDto, StackResponseDto, StackSearchDto, StackUpdateDto } from 'src/dtos/stack.dto'; @@ -15,9 +16,10 @@ export class StackController { @Get() @Authenticated({ permission: Permission.StackRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve stacks', description: 'Retrieve a list of stacks.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) searchStacks(@Auth() auth: AuthDto, @Query() query: StackSearchDto): Promise { return this.service.search(auth, query); @@ -25,10 +27,11 @@ export class StackController { @Post() @Authenticated({ permission: Permission.StackCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Create a stack', description: 'Create a new stack by providing a name and a list of asset IDs to include in the stack. If any of the provided asset IDs are primary assets of an existing stack, the existing stack will be merged into the newly created stack.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createStack(@Auth() auth: AuthDto, @Body() dto: StackCreateDto): Promise { return this.service.create(auth, dto); @@ -37,9 +40,10 @@ export class StackController { @Delete() @Authenticated({ permission: Permission.StackDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete stacks', description: 'Delete multiple stacks by providing a list of stack IDs.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteStacks(@Auth() auth: AuthDto, @Body() dto: BulkIdsDto): Promise { return this.service.deleteAll(auth, dto); @@ -47,9 +51,10 @@ export class StackController { @Get(':id') @Authenticated({ permission: Permission.StackRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve a stack', description: 'Retrieve a specific stack by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getStack(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.get(auth, id); @@ -57,9 +62,10 @@ export class StackController { @Put(':id') @Authenticated({ permission: Permission.StackUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Update a stack', description: 'Update an existing stack by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateStack( @Auth() auth: AuthDto, @@ -72,9 +78,10 @@ export class StackController { @Delete(':id') @Authenticated({ permission: Permission.StackDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete a stack', description: 'Delete a specific stack by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteStack(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.delete(auth, id); @@ -83,9 +90,10 @@ export class StackController { @Delete(':id/assets/:assetId') @Authenticated({ permission: Permission.StackUpdate }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Remove an asset from a stack', description: 'Remove a specific asset from a stack by providing the stack ID and asset ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) removeAssetFromStack(@Auth() auth: AuthDto, @Param() dto: UUIDAssetIDParamDto): Promise { return this.service.removeAsset(auth, dto); diff --git a/server/src/controllers/sync.controller.ts b/server/src/controllers/sync.controller.ts index 1f105e6b25..de94738f73 100644 --- a/server/src/controllers/sync.controller.ts +++ b/server/src/controllers/sync.controller.ts @@ -1,7 +1,7 @@ import { Body, Controller, Delete, Get, Header, HttpCode, HttpStatus, Post, Res } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; import { Response } from 'express'; -import { EndpointLifecycle } from 'src/decorators'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AssetResponseDto } from 'src/dtos/asset-response.dto'; import { AuthDto } from 'src/dtos/auth.dto'; import { @@ -29,10 +29,10 @@ export class SyncController { @Post('full-sync') @Authenticated() @HttpCode(HttpStatus.OK) - @EndpointLifecycle({ - deprecatedAt: 'v2.0.0', + @Endpoint({ summary: 'Get full sync for user', description: 'Retrieve all assets for a full synchronization for the authenticated user.', + history: new HistoryBuilder().added('v1').deprecated('v2'), }) getFullSyncForUser(@Auth() auth: AuthDto, @Body() dto: AssetFullSyncDto): Promise { return this.service.getFullSync(auth, dto); @@ -41,10 +41,10 @@ export class SyncController { @Post('delta-sync') @Authenticated() @HttpCode(HttpStatus.OK) - @EndpointLifecycle({ - deprecatedAt: 'v2.0.0', + @Endpoint({ summary: 'Get delta sync for user', description: 'Retrieve changed assets since the last sync for the authenticated user.', + history: new HistoryBuilder().added('v1').deprecated('v2'), }) getDeltaSync(@Auth() auth: AuthDto, @Body() dto: AssetDeltaSyncDto): Promise { return this.service.getDeltaSync(auth, dto); @@ -54,10 +54,11 @@ export class SyncController { @Authenticated({ permission: Permission.SyncStream }) @Header('Content-Type', 'application/jsonlines+json') @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Stream sync changes', description: 'Retrieve a JSON lines streamed response of changes for synchronization. This endpoint is used by the mobile app to efficiently stay up to date with changes.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async getSyncStream(@Auth() auth: AuthDto, @Res() res: Response, @Body() dto: SyncStreamDto) { try { @@ -70,9 +71,10 @@ export class SyncController { @Get('ack') @Authenticated({ permission: Permission.SyncCheckpointRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve acknowledgements', description: 'Retrieve the synchronization acknowledgments for the current session.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getSyncAck(@Auth() auth: AuthDto): Promise { return this.service.getAcks(auth); @@ -81,10 +83,11 @@ export class SyncController { @Post('ack') @Authenticated({ permission: Permission.SyncCheckpointUpdate }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Acknowledge changes', description: 'Send a list of synchronization acknowledgements to confirm that the latest changes have been received.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) sendSyncAck(@Auth() auth: AuthDto, @Body() dto: SyncAckSetDto) { return this.service.setAcks(auth, dto); @@ -93,9 +96,10 @@ export class SyncController { @Delete('ack') @Authenticated({ permission: Permission.SyncCheckpointDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete acknowledgements', description: 'Delete specific synchronization acknowledgments.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteSyncAck(@Auth() auth: AuthDto, @Body() dto: SyncAckDeleteDto): Promise { return this.service.deleteAcks(auth, dto); diff --git a/server/src/controllers/system-config.controller.ts b/server/src/controllers/system-config.controller.ts index 66d62135b7..6b79b38d98 100644 --- a/server/src/controllers/system-config.controller.ts +++ b/server/src/controllers/system-config.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Get, Put } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { SystemConfigDto, SystemConfigTemplateStorageOptionDto } from 'src/dtos/system-config.dto'; import { ApiTag, Permission } from 'src/enum'; import { Authenticated } from 'src/middleware/auth.guard'; @@ -16,16 +17,21 @@ export class SystemConfigController { @Get() @Authenticated({ permission: Permission.SystemConfigRead, admin: true }) - @ApiOperation({ summary: 'Get system configuration', description: 'Retrieve the current system configuration.' }) + @Endpoint({ + summary: 'Get system configuration', + description: 'Retrieve the current system configuration.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) getConfig(): Promise { return this.service.getSystemConfig(); } @Get('defaults') @Authenticated({ permission: Permission.SystemConfigRead, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Get system configuration defaults', description: 'Retrieve the default values for the system configuration.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getConfigDefaults(): SystemConfigDto { return this.service.getDefaults(); @@ -33,9 +39,10 @@ export class SystemConfigController { @Put() @Authenticated({ permission: Permission.SystemConfigUpdate, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Update system configuration', description: 'Update the system configuration with a new system configuration.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateConfig(@Body() dto: SystemConfigDto): Promise { return this.service.updateSystemConfig(dto); @@ -43,9 +50,10 @@ export class SystemConfigController { @Get('storage-template-options') @Authenticated({ permission: Permission.SystemConfigRead, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Get storage template options', description: 'Retrieve exemplary storage template options.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getStorageTemplateOptions(): SystemConfigTemplateStorageOptionDto { return this.storageTemplateService.getStorageTemplateOptions(); diff --git a/server/src/controllers/system-metadata.controller.ts b/server/src/controllers/system-metadata.controller.ts index f97eb3877c..8f73def3f7 100644 --- a/server/src/controllers/system-metadata.controller.ts +++ b/server/src/controllers/system-metadata.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Get, HttpCode, HttpStatus, Post } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AdminOnboardingUpdateDto, ReverseGeocodingStateResponseDto, @@ -16,9 +17,10 @@ export class SystemMetadataController { @Get('admin-onboarding') @Authenticated({ permission: Permission.SystemMetadataRead, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve admin onboarding', description: 'Retrieve the current admin onboarding status.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAdminOnboarding(): Promise { return this.service.getAdminOnboarding(); @@ -27,9 +29,10 @@ export class SystemMetadataController { @Post('admin-onboarding') @Authenticated({ permission: Permission.SystemMetadataUpdate, admin: true }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Update admin onboarding', description: 'Update the admin onboarding status.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateAdminOnboarding(@Body() dto: AdminOnboardingUpdateDto): Promise { return this.service.updateAdminOnboarding(dto); @@ -37,9 +40,10 @@ export class SystemMetadataController { @Get('reverse-geocoding-state') @Authenticated({ permission: Permission.SystemMetadataRead, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve reverse geocoding state', description: 'Retrieve the current state of the reverse geocoding import.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getReverseGeocodingState(): Promise { return this.service.getReverseGeocodingState(); @@ -47,9 +51,10 @@ export class SystemMetadataController { @Get('version-check-state') @Authenticated({ permission: Permission.SystemMetadataRead, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve version check state', description: 'Retrieve the current state of the version check process.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getVersionCheckState(): Promise { return this.service.getVersionCheckState(); diff --git a/server/src/controllers/tag.controller.ts b/server/src/controllers/tag.controller.ts index 514718f106..101e89f3a5 100644 --- a/server/src/controllers/tag.controller.ts +++ b/server/src/controllers/tag.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { BulkIdResponseDto, BulkIdsDto } from 'src/dtos/asset-ids.response.dto'; import { AuthDto } from 'src/dtos/auth.dto'; import { @@ -22,9 +23,10 @@ export class TagController { @Post() @Authenticated({ permission: Permission.TagCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Create a tag', description: 'Create a new tag by providing a name and optional color.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createTag(@Auth() auth: AuthDto, @Body() dto: TagCreateDto): Promise { return this.service.create(auth, dto); @@ -32,9 +34,10 @@ export class TagController { @Get() @Authenticated({ permission: Permission.TagRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve tags', description: 'Retrieve a list of all tags.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAllTags(@Auth() auth: AuthDto): Promise { return this.service.getAll(auth); @@ -42,9 +45,10 @@ export class TagController { @Put() @Authenticated({ permission: Permission.TagCreate }) - @ApiOperation({ + @Endpoint({ summary: 'Upsert tags', description: 'Create or update multiple tags in a single request.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) upsertTags(@Auth() auth: AuthDto, @Body() dto: TagUpsertDto): Promise { return this.service.upsert(auth, dto); @@ -52,9 +56,10 @@ export class TagController { @Put('assets') @Authenticated({ permission: Permission.TagAsset }) - @ApiOperation({ + @Endpoint({ summary: 'Tag assets', description: 'Add multiple tags to multiple assets in a single request.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) bulkTagAssets(@Auth() auth: AuthDto, @Body() dto: TagBulkAssetsDto): Promise { return this.service.bulkTagAssets(auth, dto); @@ -62,9 +67,10 @@ export class TagController { @Get(':id') @Authenticated({ permission: Permission.TagRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve a tag', description: 'Retrieve a specific tag by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getTagById(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.get(auth, id); @@ -72,9 +78,10 @@ export class TagController { @Put(':id') @Authenticated({ permission: Permission.TagUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Update a tag', description: 'Update an existing tag identified by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateTag(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto, @Body() dto: TagUpdateDto): Promise { return this.service.update(auth, id, dto); @@ -83,9 +90,10 @@ export class TagController { @Delete(':id') @Authenticated({ permission: Permission.TagDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete a tag', description: 'Delete a specific tag by its ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteTag(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.remove(auth, id); @@ -93,9 +101,10 @@ export class TagController { @Put(':id/assets') @Authenticated({ permission: Permission.TagAsset }) - @ApiOperation({ + @Endpoint({ summary: 'Tag assets', description: 'Add a tag to all the specified assets.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) tagAssets( @Auth() auth: AuthDto, @@ -107,9 +116,10 @@ export class TagController { @Delete(':id/assets') @Authenticated({ permission: Permission.TagAsset }) - @ApiOperation({ + @Endpoint({ summary: 'Untag assets', description: 'Remove a tag from all the specified assets.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) untagAssets( @Auth() auth: AuthDto, diff --git a/server/src/controllers/timeline.controller.ts b/server/src/controllers/timeline.controller.ts index c2d3284fd4..f1789a79e8 100644 --- a/server/src/controllers/timeline.controller.ts +++ b/server/src/controllers/timeline.controller.ts @@ -1,5 +1,6 @@ import { Controller, Get, Header, Query } from '@nestjs/common'; -import { ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiOkResponse, ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AuthDto } from 'src/dtos/auth.dto'; import { TimeBucketAssetDto, TimeBucketAssetResponseDto, TimeBucketDto } from 'src/dtos/time-bucket.dto'; import { ApiTag, Permission } from 'src/enum'; @@ -13,7 +14,11 @@ export class TimelineController { @Get('buckets') @Authenticated({ permission: Permission.AssetRead, sharedLink: true }) - @ApiOperation({ summary: 'Get time buckets', description: 'Retrieve a list of all minimal time buckets.' }) + @Endpoint({ + summary: 'Get time buckets', + description: 'Retrieve a list of all minimal time buckets.', + history: new HistoryBuilder().added('v1').internal('v1'), + }) getTimeBuckets(@Auth() auth: AuthDto, @Query() dto: TimeBucketDto) { return this.service.getTimeBuckets(auth, dto); } @@ -22,9 +27,10 @@ export class TimelineController { @Authenticated({ permission: Permission.AssetRead, sharedLink: true }) @ApiOkResponse({ type: TimeBucketAssetResponseDto }) @Header('Content-Type', 'application/json') - @ApiOperation({ + @Endpoint({ summary: 'Get time bucket', description: 'Retrieve a string of all asset ids in a given time bucket.', + history: new HistoryBuilder().added('v1').internal('v1'), }) getTimeBucket(@Auth() auth: AuthDto, @Query() dto: TimeBucketAssetDto) { return this.service.getTimeBucket(auth, dto); diff --git a/server/src/controllers/trash.controller.ts b/server/src/controllers/trash.controller.ts index 1b7ab6a39e..ec37c63ecc 100644 --- a/server/src/controllers/trash.controller.ts +++ b/server/src/controllers/trash.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, HttpCode, HttpStatus, Post } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { BulkIdsDto } from 'src/dtos/asset-ids.response.dto'; import { AuthDto } from 'src/dtos/auth.dto'; import { TrashResponseDto } from 'src/dtos/trash.dto'; @@ -15,9 +16,10 @@ export class TrashController { @Post('empty') @Authenticated({ permission: Permission.AssetDelete }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Empty trash', description: 'Permanently delete all items in the trash.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) emptyTrash(@Auth() auth: AuthDto): Promise { return this.service.empty(auth); @@ -26,9 +28,10 @@ export class TrashController { @Post('restore') @Authenticated({ permission: Permission.AssetDelete }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Restore trash', description: 'Restore all items in the trash.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) restoreTrash(@Auth() auth: AuthDto): Promise { return this.service.restore(auth); @@ -37,9 +40,10 @@ export class TrashController { @Post('restore/assets') @Authenticated({ permission: Permission.AssetDelete }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Restore assets', description: 'Restore specific assets from the trash.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) restoreAssets(@Auth() auth: AuthDto, @Body() dto: BulkIdsDto): Promise { return this.service.restoreAssets(auth, dto); diff --git a/server/src/controllers/user-admin.controller.ts b/server/src/controllers/user-admin.controller.ts index 466cbb6f10..6dd919e193 100644 --- a/server/src/controllers/user-admin.controller.ts +++ b/server/src/controllers/user-admin.controller.ts @@ -1,5 +1,6 @@ import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post, Put, Query } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AssetStatsDto, AssetStatsResponseDto } from 'src/dtos/asset.dto'; import { AuthDto } from 'src/dtos/auth.dto'; import { SessionResponseDto } from 'src/dtos/session.dto'; @@ -23,9 +24,10 @@ export class UserAdminController { @Get() @Authenticated({ permission: Permission.AdminUserRead, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Search users', description: 'Search for users.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) searchUsersAdmin(@Auth() auth: AuthDto, @Query() dto: UserAdminSearchDto): Promise { return this.service.search(auth, dto); @@ -33,9 +35,10 @@ export class UserAdminController { @Post() @Authenticated({ permission: Permission.AdminUserCreate, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Create a user', description: 'Create a new user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createUserAdmin(@Body() createUserDto: UserAdminCreateDto): Promise { return this.service.create(createUserDto); @@ -43,9 +46,10 @@ export class UserAdminController { @Get(':id') @Authenticated({ permission: Permission.AdminUserRead, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve a user', description: 'Retrieve a specific user by their ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getUserAdmin(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.get(auth, id); @@ -53,9 +57,10 @@ export class UserAdminController { @Put(':id') @Authenticated({ permission: Permission.AdminUserUpdate, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Update a user', description: 'Update an existing user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateUserAdmin( @Auth() auth: AuthDto, @@ -67,9 +72,10 @@ export class UserAdminController { @Delete(':id') @Authenticated({ permission: Permission.AdminUserDelete, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Delete a user', description: 'Delete a user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteUserAdmin( @Auth() auth: AuthDto, @@ -81,9 +87,10 @@ export class UserAdminController { @Get(':id/sessions') @Authenticated({ permission: Permission.AdminSessionRead, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve user sessions', description: 'Retrieve all sessions for a specific user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getUserSessionsAdmin(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.getSessions(auth, id); @@ -91,9 +98,10 @@ export class UserAdminController { @Get(':id/statistics') @Authenticated({ permission: Permission.AdminUserRead, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve user statistics', description: 'Retrieve asset statistics for a specific user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getUserStatisticsAdmin( @Auth() auth: AuthDto, @@ -105,9 +113,10 @@ export class UserAdminController { @Get(':id/preferences') @Authenticated({ permission: Permission.AdminUserRead, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve user preferences', description: 'Retrieve the preferences of a specific user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getUserPreferencesAdmin(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.getPreferences(auth, id); @@ -115,9 +124,10 @@ export class UserAdminController { @Put(':id/preferences') @Authenticated({ permission: Permission.AdminUserUpdate, admin: true }) - @ApiOperation({ + @Endpoint({ summary: 'Update user preferences', description: 'Update the preferences of a specific user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) updateUserPreferencesAdmin( @Auth() auth: AuthDto, @@ -130,9 +140,10 @@ export class UserAdminController { @Post(':id/restore') @Authenticated({ permission: Permission.AdminUserDelete, admin: true }) @HttpCode(HttpStatus.OK) - @ApiOperation({ + @Endpoint({ summary: 'Restore a deleted user', description: 'Restore a previously deleted user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) restoreUserAdmin(@Auth() auth: AuthDto, @Param() { id }: UUIDParamDto): Promise { return this.service.restore(auth, id); diff --git a/server/src/controllers/user.controller.ts b/server/src/controllers/user.controller.ts index d76daaa0d5..9c0dd3db7a 100644 --- a/server/src/controllers/user.controller.ts +++ b/server/src/controllers/user.controller.ts @@ -13,8 +13,9 @@ import { UploadedFile, UseInterceptors, } from '@nestjs/common'; -import { ApiBody, ApiConsumes, ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiBody, ApiConsumes, ApiTags } from '@nestjs/swagger'; import { NextFunction, Response } from 'express'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AuthDto } from 'src/dtos/auth.dto'; import { LicenseKeyDto, LicenseResponseDto } from 'src/dtos/license.dto'; import { OnboardingDto, OnboardingResponseDto } from 'src/dtos/onboarding.dto'; @@ -39,16 +40,21 @@ export class UserController { @Get() @Authenticated({ permission: Permission.UserRead }) - @ApiOperation({ summary: 'Get all users', description: 'Retrieve a list of all users on the server.' }) + @Endpoint({ + summary: 'Get all users', + description: 'Retrieve a list of all users on the server.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) searchUsers(@Auth() auth: AuthDto): Promise { return this.service.search(auth); } @Get('me') @Authenticated({ permission: Permission.UserRead }) - @ApiOperation({ + @Endpoint({ summary: 'Get current user', description: 'Retrieve information about the user making the API request.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getMyUser(@Auth() auth: AuthDto): Promise { return this.service.getMe(auth); @@ -56,21 +62,33 @@ export class UserController { @Put('me') @Authenticated({ permission: Permission.UserUpdate }) - @ApiOperation({ summary: 'Update current user', description: 'Update the current user making teh API request.' }) + @Endpoint({ + summary: 'Update current user', + description: 'Update the current user making teh API request.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) updateMyUser(@Auth() auth: AuthDto, @Body() dto: UserUpdateMeDto): Promise { return this.service.updateMe(auth, dto); } @Get('me/preferences') @Authenticated({ permission: Permission.UserPreferenceRead }) - @ApiOperation({ summary: 'Get my preferences', description: 'Retrieve the preferences for the current user.' }) + @Endpoint({ + summary: 'Get my preferences', + description: 'Retrieve the preferences for the current user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) getMyPreferences(@Auth() auth: AuthDto): Promise { return this.service.getMyPreferences(auth); } @Put('me/preferences') @Authenticated({ permission: Permission.UserPreferenceUpdate }) - @ApiOperation({ summary: 'Update my preferences', description: 'Update the preferences of the current user.' }) + @Endpoint({ + summary: 'Update my preferences', + description: 'Update the preferences of the current user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), + }) updateMyPreferences( @Auth() auth: AuthDto, @Body() dto: UserPreferencesUpdateDto, @@ -80,9 +98,10 @@ export class UserController { @Get('me/license') @Authenticated({ permission: Permission.UserLicenseRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve user product key', description: 'Retrieve information about whether the current user has a registered product key.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getUserLicense(@Auth() auth: AuthDto): Promise { return this.service.getLicense(auth); @@ -90,9 +109,10 @@ export class UserController { @Put('me/license') @Authenticated({ permission: Permission.UserLicenseUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Set user product key', description: 'Register a product key for the current user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async setUserLicense(@Auth() auth: AuthDto, @Body() license: LicenseKeyDto): Promise { return this.service.setLicense(auth, license); @@ -101,9 +121,10 @@ export class UserController { @Delete('me/license') @Authenticated({ permission: Permission.UserLicenseDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete user product key', description: 'Delete the registered product key for the current user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async deleteUserLicense(@Auth() auth: AuthDto): Promise { await this.service.deleteLicense(auth); @@ -111,9 +132,10 @@ export class UserController { @Get('me/onboarding') @Authenticated({ permission: Permission.UserOnboardingRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve user onboarding', description: 'Retrieve the onboarding status of the current user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getUserOnboarding(@Auth() auth: AuthDto): Promise { return this.service.getOnboarding(auth); @@ -121,9 +143,10 @@ export class UserController { @Put('me/onboarding') @Authenticated({ permission: Permission.UserOnboardingUpdate }) - @ApiOperation({ + @Endpoint({ summary: 'Update user onboarding', description: 'Update the onboarding status of the current user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async setUserOnboarding(@Auth() auth: AuthDto, @Body() Onboarding: OnboardingDto): Promise { return this.service.setOnboarding(auth, Onboarding); @@ -132,9 +155,10 @@ export class UserController { @Delete('me/onboarding') @Authenticated({ permission: Permission.UserOnboardingDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete user onboarding', description: 'Delete the onboarding status of the current user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async deleteUserOnboarding(@Auth() auth: AuthDto): Promise { await this.service.deleteOnboarding(auth); @@ -142,9 +166,10 @@ export class UserController { @Get(':id') @Authenticated({ permission: Permission.UserRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve a user', description: 'Retrieve a specific user by their ID.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getUser(@Param() { id }: UUIDParamDto): Promise { return this.service.get(id); @@ -155,9 +180,10 @@ export class UserController { @UseInterceptors(FileUploadInterceptor) @ApiConsumes('multipart/form-data') @ApiBody({ description: 'A new avatar for the user', type: CreateProfileImageDto }) - @ApiOperation({ + @Endpoint({ summary: 'Create user profile image', description: 'Upload and set a new profile image for the current user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) createProfileImage( @Auth() auth: AuthDto, @@ -169,9 +195,10 @@ export class UserController { @Delete('profile-image') @Authenticated({ permission: Permission.UserProfileImageDelete }) @HttpCode(HttpStatus.NO_CONTENT) - @ApiOperation({ + @Endpoint({ summary: 'Delete user profile image', description: 'Delete the profile image of the current user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) deleteProfileImage(@Auth() auth: AuthDto): Promise { return this.service.deleteProfileImage(auth); @@ -180,9 +207,10 @@ export class UserController { @Get(':id/profile-image') @FileResponse() @Authenticated({ permission: Permission.UserProfileImageRead }) - @ApiOperation({ + @Endpoint({ summary: 'Retrieve user profile image', description: 'Retrieve the profile image file for a user.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) async getProfileImage(@Res() res: Response, @Next() next: NextFunction, @Param() { id }: UUIDParamDto) { await sendFile(res, next, () => this.service.getProfileImage(id), this.logger); diff --git a/server/src/controllers/view.controller.ts b/server/src/controllers/view.controller.ts index 8d0cbb0d96..8a977e15bc 100644 --- a/server/src/controllers/view.controller.ts +++ b/server/src/controllers/view.controller.ts @@ -1,5 +1,6 @@ import { Controller, Get, Query } from '@nestjs/common'; -import { ApiOperation, ApiTags } from '@nestjs/swagger'; +import { ApiTags } from '@nestjs/swagger'; +import { Endpoint, HistoryBuilder } from 'src/decorators'; import { AssetResponseDto } from 'src/dtos/asset-response.dto'; import { AuthDto } from 'src/dtos/auth.dto'; import { ApiTag } from 'src/enum'; @@ -13,9 +14,10 @@ export class ViewController { @Get('folder/unique-paths') @Authenticated() - @ApiOperation({ + @Endpoint({ summary: 'Retrieve unique paths', description: 'Retrieve a list of unique folder paths from asset original paths.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getUniqueOriginalPaths(@Auth() auth: AuthDto): Promise { return this.service.getUniqueOriginalPaths(auth); @@ -23,9 +25,10 @@ export class ViewController { @Get('folder') @Authenticated() - @ApiOperation({ + @Endpoint({ summary: 'Retrieve assets by original path', description: 'Retrieve assets that are children of a specific folder.', + history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAssetsByOriginalPath(@Auth() auth: AuthDto, @Query('path') path: string): Promise { return this.service.getAssetsByOriginalPath(auth, path); diff --git a/server/src/cores/storage.core.spec.ts b/server/src/cores/storage.core.spec.ts index ed446f9259..08e410bbe3 100644 --- a/server/src/cores/storage.core.spec.ts +++ b/server/src/cores/storage.core.spec.ts @@ -2,8 +2,6 @@ import { StorageCore } from 'src/cores/storage.core'; import { vitest } from 'vitest'; vitest.mock('src/constants', () => ({ - ADDED_IN_PREFIX: 'This property was added in ', - DEPRECATED_IN_PREFIX: 'This property was deprecated in ', IWorker: 'IWorker', })); diff --git a/server/src/decorators.ts b/server/src/decorators.ts index e9f27fa9ec..054bbf8fec 100644 --- a/server/src/decorators.ts +++ b/server/src/decorators.ts @@ -1,8 +1,7 @@ import { SetMetadata, applyDecorators } from '@nestjs/common'; -import { ApiExtension, ApiOperation, ApiOperationOptions, ApiProperty, ApiTags } from '@nestjs/swagger'; +import { ApiOperation, ApiOperationOptions, ApiProperty, ApiPropertyOptions, ApiTags } from '@nestjs/swagger'; import _ from 'lodash'; -import { ADDED_IN_PREFIX, DEPRECATED_IN_PREFIX, LIFECYCLE_EXTENSION } from 'src/constants'; -import { ApiTag, ImmichWorker, JobName, MetadataKey, QueueName } from 'src/enum'; +import { ApiCustomExtension, ApiTag, ImmichWorker, JobName, MetadataKey, QueueName } from 'src/enum'; import { EmitEvent } from 'src/repositories/event.repository'; import { immich_uuid_v7, updated_at } from 'src/schema/functions'; import { BeforeUpdateTrigger, Column, ColumnOptions } from 'src/sql-tools'; @@ -153,39 +152,122 @@ export type JobConfig = { }; export const OnJob = (config: JobConfig) => SetMetadata(MetadataKey.JobConfig, config); -type LifecycleRelease = 'NEXT_RELEASE' | string; -type LifecycleMetadata = { - addedAt?: LifecycleRelease; - deprecatedAt?: LifecycleRelease; -}; +type EndpointOptions = ApiOperationOptions & { history?: HistoryBuilder }; +export const Endpoint = ({ history, ...options }: EndpointOptions) => { + const decorators: MethodDecorator[] = []; + const extensions = history?.getExtensions() ?? {}; -export const EndpointLifecycle = ({ - addedAt, - deprecatedAt, - description, - ...options -}: LifecycleMetadata & ApiOperationOptions) => { - const decorators: MethodDecorator[] = [ApiExtension(LIFECYCLE_EXTENSION, { addedAt, deprecatedAt })]; - if (deprecatedAt) { - decorators.push( - ApiTags(ApiTag.Deprecated), - ApiOperation({ - deprecated: true, - description: DEPRECATED_IN_PREFIX + deprecatedAt + (description ? `. ${description}` : ''), - ...options, - }), - ); + if (!extensions[ApiCustomExtension.History]) { + console.log(`Missing history for endpoint: ${options.summary}`); } + if (history?.isDeprecated()) { + options.deprecated = true; + decorators.push(ApiTags(ApiTag.Deprecated)); + } + + decorators.push(ApiOperation({ ...options, ...extensions })); + return applyDecorators(...decorators); }; -export const PropertyLifecycle = ({ addedAt, deprecatedAt }: LifecycleMetadata) => { - const decorators: PropertyDecorator[] = []; - decorators.push(ApiProperty({ description: ADDED_IN_PREFIX + addedAt })); - if (deprecatedAt) { - decorators.push(ApiProperty({ deprecated: true, description: DEPRECATED_IN_PREFIX + deprecatedAt })); +type PropertyOptions = ApiPropertyOptions & { history?: HistoryBuilder }; +export const Property = ({ history, ...options }: PropertyOptions) => { + const extensions = history?.getExtensions() ?? {}; + + if (history?.isDeprecated()) { + options.deprecated = true; } - return applyDecorators(...decorators); + return ApiProperty({ ...options, ...extensions }); }; + +type HistoryEntry = { + version: string; + state: ApiState | 'Added' | 'Updated'; + description?: string; + replacementId?: string; +}; + +type DeprecatedOptions = { + /** replacement operationId */ + replacementId?: string; +}; + +type CustomExtensions = { + [ApiCustomExtension.State]?: ApiState; + [ApiCustomExtension.History]?: HistoryEntry[]; +}; + +enum ApiState { + 'Stable' = 'Stable', + 'Alpha' = 'Alpha', + 'Beta' = 'Beta', + 'Internal' = 'Internal', + 'Deprecated' = 'Deprecated', +} +export class HistoryBuilder { + private hasDeprecated = false; + private items: HistoryEntry[] = []; + + added(version: string, description?: string) { + return this.push({ version, state: 'Added', description }); + } + + updated(version: string, description: string) { + return this.push({ version, state: 'Updated', description }); + } + + alpha(version: string) { + return this.push({ version, state: ApiState.Alpha }); + } + + beta(version: string) { + return this.push({ version, state: ApiState.Beta }); + } + + internal(version: string) { + return this.push({ version, state: ApiState.Internal }); + } + + stable(version: string) { + return this.push({ version, state: ApiState.Stable }); + } + + deprecated(version: string, options?: DeprecatedOptions) { + const { replacementId } = options || {}; + this.hasDeprecated = true; + return this.push({ version, state: ApiState.Deprecated, replacementId }); + } + + isDeprecated(): boolean { + return this.hasDeprecated; + } + + getExtensions() { + const extensions: CustomExtensions = {}; + + if (this.items.length > 0) { + extensions[ApiCustomExtension.History] = this.items; + } + + for (const item of this.items.toReversed()) { + if (item.state === 'Added' || item.state === 'Updated') { + continue; + } + + extensions[ApiCustomExtension.State] = item.state; + break; + } + + return extensions; + } + + private push(item: HistoryEntry) { + if (!item.version.startsWith('v')) { + throw new Error(`Version string must start with 'v': received '${JSON.stringify(item)}'`); + } + this.items.push(item); + return this; + } +} diff --git a/server/src/dtos/asset-response.dto.ts b/server/src/dtos/asset-response.dto.ts index b3fecf2f8f..1716c327f3 100644 --- a/server/src/dtos/asset-response.dto.ts +++ b/server/src/dtos/asset-response.dto.ts @@ -1,7 +1,7 @@ import { ApiProperty } from '@nestjs/swagger'; import { Selectable } from 'kysely'; import { AssetFace, AssetFile, Exif, Stack, Tag, User } from 'src/database'; -import { PropertyLifecycle } from 'src/decorators'; +import { HistoryBuilder, Property } from 'src/decorators'; import { AuthDto } from 'src/dtos/auth.dto'; import { ExifResponseDto, mapExif } from 'src/dtos/exif.dto'; import { @@ -48,7 +48,7 @@ export class AssetResponseDto extends SanitizedAssetResponseDto { deviceId!: string; ownerId!: string; owner?: UserResponseDto; - @PropertyLifecycle({ deprecatedAt: 'v1.106.0' }) + @Property({ history: new HistoryBuilder().added('v1').deprecated('v1') }) libraryId?: string | null; originalPath!: string; originalFileName!: string; @@ -91,7 +91,7 @@ export class AssetResponseDto extends SanitizedAssetResponseDto { stack?: AssetStackResponseDto | null; duplicateId?: string | null; - @PropertyLifecycle({ deprecatedAt: 'v1.113.0' }) + @Property({ history: new HistoryBuilder().added('v1').deprecated('v1.113.0') }) resized?: boolean; } diff --git a/server/src/dtos/person.dto.ts b/server/src/dtos/person.dto.ts index f9b41627d9..3c90cfdc59 100644 --- a/server/src/dtos/person.dto.ts +++ b/server/src/dtos/person.dto.ts @@ -4,7 +4,7 @@ import { IsArray, IsInt, IsNotEmpty, IsNumber, IsString, Max, Min, ValidateNeste import { Selectable } from 'kysely'; import { DateTime } from 'luxon'; import { AssetFace, Person } from 'src/database'; -import { PropertyLifecycle } from 'src/decorators'; +import { HistoryBuilder, Property } from 'src/decorators'; import { AuthDto } from 'src/dtos/auth.dto'; import { SourceType } from 'src/enum'; import { AssetFaceTable } from 'src/schema/tables/asset-face.table'; @@ -111,11 +111,11 @@ export class PersonResponseDto { birthDate!: string | null; thumbnailPath!: string; isHidden!: boolean; - @PropertyLifecycle({ addedAt: 'v1.107.0' }) + @Property({ history: new HistoryBuilder().added('v1.107.0').stable('v2') }) updatedAt?: Date; - @PropertyLifecycle({ addedAt: 'v1.126.0' }) + @Property({ history: new HistoryBuilder().added('v1.126.0').stable('v2') }) isFavorite?: boolean; - @PropertyLifecycle({ addedAt: 'v1.126.0' }) + @Property({ history: new HistoryBuilder().added('v1.126.0').stable('v2') }) color?: string; } @@ -216,7 +216,7 @@ export class PeopleResponseDto { people!: PersonResponseDto[]; // TODO: make required after a few versions - @PropertyLifecycle({ addedAt: 'v1.110.0' }) + @Property({ history: new HistoryBuilder().added('v1.110.0').stable('v2') }) hasNextPage?: boolean; } diff --git a/server/src/dtos/search.dto.ts b/server/src/dtos/search.dto.ts index 591f1acd82..068cd6630c 100644 --- a/server/src/dtos/search.dto.ts +++ b/server/src/dtos/search.dto.ts @@ -2,7 +2,7 @@ import { ApiProperty } from '@nestjs/swagger'; import { Type } from 'class-transformer'; import { IsInt, IsNotEmpty, IsString, Max, Min } from 'class-validator'; import { Place } from 'src/database'; -import { PropertyLifecycle } from 'src/decorators'; +import { HistoryBuilder, Property } from 'src/decorators'; import { AlbumResponseDto } from 'src/dtos/album.dto'; import { AssetResponseDto } from 'src/dtos/asset-response.dto'; import { AssetOrder, AssetType, AssetVisibility } from 'src/enum'; @@ -282,7 +282,7 @@ export class SearchSuggestionRequestDto { lensModel?: string; @ValidateBoolean({ optional: true }) - @PropertyLifecycle({ addedAt: 'v111.0.0' }) + @Property({ history: new HistoryBuilder().added('v1.111.0').stable('v2') }) includeNull?: boolean; } diff --git a/server/src/enum.ts b/server/src/enum.ts index 24f307f07a..c706c1da7c 100644 --- a/server/src/enum.ts +++ b/server/src/enum.ts @@ -434,6 +434,8 @@ export enum LogLevel { export enum ApiCustomExtension { Permission = 'x-immich-permission', AdminOnly = 'x-immich-admin-only', + History = 'x-immich-history', + State = 'x-immich-state', } export enum MetadataKey { diff --git a/server/src/utils/lifecycle.ts b/server/src/utils/lifecycle.ts deleted file mode 100644 index 16793f6922..0000000000 --- a/server/src/utils/lifecycle.ts +++ /dev/null @@ -1,91 +0,0 @@ -#!/usr/bin/env node -import { OpenAPIObject } from '@nestjs/swagger'; -import { SchemaObject } from '@nestjs/swagger/dist/interfaces/open-api-spec.interface'; -import { readFileSync } from 'node:fs'; -import { resolve } from 'node:path'; -import { SemVer } from 'semver'; -import { ADDED_IN_PREFIX, DEPRECATED_IN_PREFIX, LIFECYCLE_EXTENSION, NEXT_RELEASE } from 'src/constants'; - -const outputPath = resolve(process.cwd(), '../open-api/immich-openapi-specs.json'); -const spec = JSON.parse(readFileSync(outputPath).toString()) as OpenAPIObject; - -type Items = { - oldEndpoints: Endpoint[]; - newEndpoints: Endpoint[]; - oldProperties: Property[]; - newProperties: Property[]; -}; -type Endpoint = { url: string; method: string; endpoint: any }; -type Property = { schema: string; property: string }; - -const metadata: Record = {}; -const trackVersion = (version: string) => { - if (!metadata[version]) { - metadata[version] = { - oldEndpoints: [], - newEndpoints: [], - oldProperties: [], - newProperties: [], - }; - } - return metadata[version]; -}; - -for (const [url, methods] of Object.entries(spec.paths)) { - for (const [method, endpoint] of Object.entries(methods) as Array<[string, any]>) { - const deprecatedAt = endpoint[LIFECYCLE_EXTENSION]?.deprecatedAt; - if (deprecatedAt) { - trackVersion(deprecatedAt).oldEndpoints.push({ url, method, endpoint }); - } - - const addedAt = endpoint[LIFECYCLE_EXTENSION]?.addedAt; - if (addedAt) { - trackVersion(addedAt).newEndpoints.push({ url, method, endpoint }); - } - } -} - -for (const [schemaName, schema] of Object.entries(spec.components?.schemas || {})) { - for (const [propertyName, property] of Object.entries((schema as SchemaObject).properties || {})) { - const propertySchema = property as SchemaObject; - if (propertySchema.description?.startsWith(DEPRECATED_IN_PREFIX)) { - const deprecatedAt = propertySchema.description.replace(DEPRECATED_IN_PREFIX, '').trim(); - trackVersion(deprecatedAt).oldProperties.push({ schema: schemaName, property: propertyName }); - } - - if (propertySchema.description?.startsWith(ADDED_IN_PREFIX)) { - const addedAt = propertySchema.description.replace(ADDED_IN_PREFIX, '').trim(); - trackVersion(addedAt).newProperties.push({ schema: schemaName, property: propertyName }); - } - } -} - -const sortedVersions = Object.keys(metadata).sort((a, b) => { - if (a === NEXT_RELEASE) { - return -1; - } - - if (b === NEXT_RELEASE) { - return 1; - } - - return new SemVer(b).compare(new SemVer(a)); -}); - -for (const version of sortedVersions) { - const { oldEndpoints, newEndpoints, oldProperties, newProperties } = metadata[version]; - console.log(`\nChanges in ${version}`); - console.log('---------------------'); - for (const { url, method, endpoint } of oldEndpoints) { - console.log(`- Deprecated ${method.toUpperCase()} ${url} (${endpoint.operationId})`); - } - for (const { url, method, endpoint } of newEndpoints) { - console.log(`- Added ${method.toUpperCase()} ${url} (${endpoint.operationId})`); - } - for (const { schema, property } of oldProperties) { - console.log(`- Deprecated ${schema}.${property}`); - } - for (const { schema, property } of newProperties) { - console.log(`- Added ${schema}.${property}`); - } -}