Source Code added

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

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+OPENAPI_GENERATOR_VERSION=v7.12.0
+
+# usage: ./bin/generate-open-api.sh
+
+function dart {
+  rm -rf ../mobile/openapi
+  cd ./templates/mobile/serialization/native
+  wget -O native_class.mustache https://raw.githubusercontent.com/OpenAPITools/openapi-generator/$OPENAPI_GENERATOR_VERSION/modules/openapi-generator/src/main/resources/dart2/serialization/native/native_class.mustache
+  patch --no-backup-if-mismatch -u native_class.mustache <native_class.mustache.patch
+  patch --no-backup-if-mismatch -u native_class.mustache <native_class_nullable_items_in_arrays.patch
+
+  cd ../../
+  wget -O api.mustache https://raw.githubusercontent.com/OpenAPITools/openapi-generator/$OPENAPI_GENERATOR_VERSION/modules/openapi-generator/src/main/resources/dart2/api.mustache
+  patch --no-backup-if-mismatch -u api.mustache <api.mustache.patch
+
+  cd ../../
+  pnpm dlx @openapitools/openapi-generator-cli generate -g dart -i ./immich-openapi-specs.json -o ../mobile/openapi -t ./templates/mobile
+
+  # Post generate patches
+  patch --no-backup-if-mismatch -u ../mobile/openapi/lib/api_client.dart <./patch/api_client.dart.patch
+  patch --no-backup-if-mismatch -u ../mobile/openapi/lib/api.dart <./patch/api.dart.patch
+  patch --no-backup-if-mismatch -u ../mobile/openapi/pubspec.yaml <./patch/pubspec_immich_mobile.yaml.patch
+  # Don't include analysis_options.yaml for the generated openapi files
+  # so that language servers can properly exclude the mobile/openapi directory
+  rm ../mobile/openapi/analysis_options.yaml
+}
+
+function typescript {
+  pnpm dlx oazapfts --optimistic --argumentStyle=object --useEnumType --allSchemas immich-openapi-specs.json typescript-sdk/src/fetch-client.ts
+  pnpm --filter @immich/sdk install --frozen-lockfile
+  pnpm --filter @immich/sdk build
+}
+
+# requires server to be built
+(
+  cd ..
+  SHARP_IGNORE_GLOBAL_LIBVIPS=true pnpm --filter immich build
+  pnpm --filter immich sync:open-api
+)
+
+if [[ $1 == 'dart' ]]; then
+  dart
+elif [[ $1 == 'typescript' ]]; then
+  typescript
+else
+  dart
+  typescript
+fi

open-api/openapitools.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
+  "spaces": 2,
+  "generator-cli": {
+    "version": "7.8.0"
+  }
+}

open-api/patch/api.dart.patch

@@ -0,0 +1,9 @@
+@@ -15,6 +15,8 @@
+ import 'dart:io';
+
+ import 'package:collection/collection.dart';
++import 'package:flutter/foundation.dart';
++import 'package:immich_mobile/utils/openapi_patching.dart';
+ import 'package:http/http.dart';
+ import 'package:intl/intl.dart';
+ import 'package:meta/meta.dart';

open-api/patch/api_client.dart.patch

@@ -0,0 +1,21 @@
+@@ -143,19 +143,19 @@
+     );
+   }
+
+-  Future<dynamic> deserializeAsync(String value, String targetType, {bool growable = false,}) async =>
++  Future<dynamic> deserializeAsync(String value, String targetType, {bool growable = false,}) =>
+     // ignore: deprecated_member_use_from_same_package
+     deserialize(value, targetType, growable: growable);
+
+   @Deprecated('Scheduled for removal in OpenAPI Generator 6.x. Use deserializeAsync() instead.')
+-  dynamic deserialize(String value, String targetType, {bool growable = false,}) {
++  Future<dynamic> deserialize(String value, String targetType, {bool growable = false,}) async {
+     // Remove all spaces. Necessary for regular expressions as well.
+     targetType = targetType.replaceAll(' ', ''); // ignore: parameter_assignments
+
+     // If the expected target type is String, nothing to do...
+     return targetType == 'String'
+       ? value
+-      : fromJson(json.decode(value), targetType, growable: growable);
++      : fromJson(await compute((String j) => json.decode(j), value), targetType, growable: growable);
+   }

open-api/patch/pubspec_immich_mobile.yaml.patch

@@ -0,0 +1,9 @@
+# Include code from immich_mobile
+@@ -13,5 +13,5 @@
+   http: '>=0.13.0 <2.0.0'
+   intl: any
+   meta: '>=1.1.8 <2.0.0'
+-dev_dependencies:
+-  test: '>=1.21.6 <1.22.0'
++  immich_mobile:
++    path: ../

open-api/templates/mobile/api.mustache

@@ -0,0 +1,194 @@
+{{>header}}
+{{>part_of}}
+{{#operations}}
+
+class {{{classname}}} {
+  {{{classname}}}([ApiClient? apiClient]) : apiClient = apiClient ?? defaultApiClient;
+
+  final ApiClient apiClient;
+  {{#operation}}
+
+  {{#summary}}
+  /// {{{.}}}
+  {{/summary}}
+  {{#notes}}
+    {{#summary}}
+  ///
+    {{/summary}}
+  /// {{{notes}}}
+  ///
+  /// Note: This method returns the HTTP [Response].
+  {{/notes}}
+  {{^notes}}
+    {{#summary}}
+  ///
+  /// Note: This method returns the HTTP [Response].
+    {{/summary}}
+    {{^summary}}
+  /// Performs an HTTP '{{{httpMethod}}} {{{path}}}' operation and returns the [Response].
+    {{/summary}}
+  {{/notes}}
+  {{#hasParams}}
+    {{#summary}}
+  ///
+    {{/summary}}
+    {{^summary}}
+      {{#notes}}
+  ///
+      {{/notes}}
+    {{/summary}}
+  /// Parameters:
+  ///
+  {{/hasParams}}
+  {{#allParams}}
+  /// * [{{{dataType}}}] {{{paramName}}}{{#required}} (required){{/required}}{{#optional}} (optional){{/optional}}:
+    {{#description}}
+  ///   {{{.}}}
+    {{/description}}
+    {{^-last}}
+  ///
+    {{/-last}}
+  {{/allParams}}
+  Future<Response> {{{nickname}}}WithHttpInfo({{#allParams}}{{#required}}{{{dataType}}} {{{paramName}}},{{^-last}} {{/-last}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{ {{#allParams}}{{^required}}{{{dataType}}}? {{{paramName}}},{{^-last}} {{/-last}}{{/required}}{{/allParams}} }{{/hasOptionalParams}}) async {
+    // ignore: prefer_const_declarations
+    final apiPath = r'{{{path}}}'{{#pathParams}}
+      .replaceAll({{=<% %>=}}'{<% baseName %>}'<%={{ }}=%>, {{{paramName}}}{{^isString}}.toString(){{/isString}}){{/pathParams}};
+
+    // ignore: prefer_final_locals
+    Object? postBody{{#bodyParam}} = {{{paramName}}}{{/bodyParam}};
+
+    final queryParams = <QueryParam>[];
+    final headerParams = <String, String>{};
+    final formParams = <String, String>{};
+    {{#hasQueryParams}}
+
+      {{#queryParams}}
+        {{^required}}
+    if ({{{paramName}}} != null) {
+          {{/required}}
+      queryParams.addAll(_queryParams('{{{collectionFormat}}}', '{{{baseName}}}', {{{paramName}}}));
+          {{^required}}
+    }
+        {{/required}}
+      {{/queryParams}}
+    {{/hasQueryParams}}
+    {{#hasHeaderParams}}
+
+      {{#headerParams}}
+        {{#required}}
+    headerParams[r'{{{baseName}}}'] = parameterToString({{{paramName}}});
+        {{/required}}
+        {{^required}}
+    if ({{{paramName}}} != null) {
+      headerParams[r'{{{baseName}}}'] = parameterToString({{{paramName}}});
+    }
+        {{/required}}
+      {{/headerParams}}
+    {{/hasHeaderParams}}
+
+    const contentTypes = <String>[{{#prioritizedContentTypes}}'{{{mediaType}}}'{{^-last}}, {{/-last}}{{/prioritizedContentTypes}}];
+
+    {{#isMultipart}}
+    bool hasFields = false;
+    final mp = MultipartRequest('{{{httpMethod}}}', Uri.parse(apiPath));
+    {{#formParams}}
+    {{^isFile}}
+    if ({{{paramName}}} != null) {
+      hasFields = true;
+      mp.fields[r'{{{baseName}}}'] = parameterToString({{{paramName}}});
+    }
+    {{/isFile}}
+    {{#isFile}}
+    if ({{{paramName}}} != null) {
+      hasFields = true;
+      mp.fields[r'{{{baseName}}}'] = {{{paramName}}}.field;
+      mp.files.add({{{paramName}}});
+    }
+    {{/isFile}}
+    {{/formParams}}
+    if (hasFields) {
+      postBody = mp;
+    }
+    {{/isMultipart}}
+    {{^isMultipart}}
+    {{#formParams}}
+    {{^isFile}}
+    if ({{{paramName}}} != null) {
+      formParams[r'{{{baseName}}}'] = parameterToString({{{paramName}}});
+    }
+    {{/isFile}}
+    {{/formParams}}
+    {{/isMultipart}}
+
+    return apiClient.invokeAPI(
+      apiPath,
+      '{{{httpMethod}}}',
+      queryParams,
+      postBody,
+      headerParams,
+      formParams,
+      contentTypes.isEmpty ? null : contentTypes.first,
+    );
+  }
+
+  {{#summary}}
+  /// {{{.}}}
+  {{/summary}}
+  {{#notes}}
+  {{#summary}}
+  ///
+  {{/summary}}
+  /// {{{notes}}}
+  {{/notes}}
+  {{#hasParams}}
+    {{#summary}}
+  ///
+    {{/summary}}
+    {{^summary}}
+      {{#notes}}
+  ///
+      {{/notes}}
+    {{/summary}}
+  /// Parameters:
+  ///
+  {{/hasParams}}
+  {{#allParams}}
+  /// * [{{{dataType}}}] {{{paramName}}}{{#required}} (required){{/required}}{{#optional}} (optional){{/optional}}:
+    {{#description}}
+  ///   {{{.}}}
+    {{/description}}
+    {{^-last}}
+  ///
+    {{/-last}}
+  {{/allParams}}
+  Future<{{#returnType}}{{{.}}}?{{/returnType}}{{^returnType}}void{{/returnType}}> {{{nickname}}}({{#allParams}}{{#required}}{{{dataType}}} {{{paramName}}},{{^-last}} {{/-last}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{ {{#allParams}}{{^required}}{{{dataType}}}? {{{paramName}}},{{^-last}} {{/-last}}{{/required}}{{/allParams}} }{{/hasOptionalParams}}) async {
+    final response = await {{{nickname}}}WithHttpInfo({{#allParams}}{{#required}}{{{paramName}}},{{^-last}} {{/-last}}{{/required}}{{/allParams}}{{#hasOptionalParams}} {{#allParams}}{{^required}}{{{paramName}}}: {{{paramName}}},{{^-last}} {{/-last}}{{/required}}{{/allParams}} {{/hasOptionalParams}});
+    if (response.statusCode >= HttpStatus.badRequest) {
+      throw ApiException(response.statusCode, await _decodeBodyBytes(response));
+    }
+    {{#returnType}}
+    // When a remote server returns no body with a status of 204, we shall not decode it.
+    // At the time of writing this, `dart:convert` will throw an "Unexpected end of input"
+    // FormatException when trying to decode an empty string.
+    if (response.body.isNotEmpty && response.statusCode != HttpStatus.noContent) {
+    {{#native_serialization}}
+    {{#isArray}}
+      final responseBody = await _decodeBodyBytes(response);
+      return (await apiClient.deserializeAsync(responseBody, '{{{returnType}}}') as List)
+        .cast<{{{returnBaseType}}}>()
+        .{{#uniqueItems}}toSet(){{/uniqueItems}}{{^uniqueItems}}toList(growable: false){{/uniqueItems}};
+    {{/isArray}}
+    {{^isArray}}
+    {{#isMap}}
+      return {{{returnType}}}.from(await apiClient.deserializeAsync(await _decodeBodyBytes(response), '{{{returnType}}}'),);
+    {{/isMap}}
+    {{^isMap}}
+      return await apiClient.deserializeAsync(await _decodeBodyBytes(response), '{{{returnType}}}',) as {{{returnType}}};
+    {{/isMap}}{{/isArray}}{{/native_serialization}}
+    }
+    return null;
+    {{/returnType}}
+  }
+  {{/operation}}
+}
+{{/operations}}

open-api/templates/mobile/api.mustache.patch

@@ -0,0 +1,29 @@
+--- api.mustache	2025-01-22 05:50:25
++++ api.mustache.modified	2025-01-22 05:52:23
+@@ -51,7 +51,7 @@
+   {{/allParams}}
+   Future<Response> {{{nickname}}}WithHttpInfo({{#allParams}}{{#required}}{{{dataType}}} {{{paramName}}},{{^-last}} {{/-last}}{{/required}}{{/allParams}}{{#hasOptionalParams}}{ {{#allParams}}{{^required}}{{{dataType}}}? {{{paramName}}},{{^-last}} {{/-last}}{{/required}}{{/allParams}} }{{/hasOptionalParams}}) async {
+     // ignore: prefer_const_declarations
+-    final path = r'{{{path}}}'{{#pathParams}}
++    final apiPath = r'{{{path}}}'{{#pathParams}}
+       .replaceAll({{=<% %>=}}'{<% baseName %>}'<%={{ }}=%>, {{{paramName}}}{{^isString}}.toString(){{/isString}}){{/pathParams}};
+ 
+     // ignore: prefer_final_locals
+@@ -90,7 +90,7 @@
+ 
+     {{#isMultipart}}
+     bool hasFields = false;
+-    final mp = MultipartRequest('{{{httpMethod}}}', Uri.parse(path));
++    final mp = MultipartRequest('{{{httpMethod}}}', Uri.parse(apiPath));
+     {{#formParams}}
+     {{^isFile}}
+     if ({{{paramName}}} != null) {
+@@ -121,7 +121,7 @@
+     {{/isMultipart}}
+ 
+     return apiClient.invokeAPI(
+-      path,
++      apiPath,
+       '{{{httpMethod}}}',
+       queryParams,
+       postBody,

open-api/templates/mobile/serialization/native/native_class.mustache

@@ -0,0 +1,296 @@
+class {{{classname}}} {
+{{>dart_constructor}}
+{{#vars}}
+  {{#description}}
+  /// {{{.}}}
+  {{/description}}
+  {{^isEnum}}
+    {{#minimum}}
+      {{#description}}
+  ///
+      {{/description}}
+  /// Minimum value: {{{.}}}
+    {{/minimum}}
+    {{#maximum}}
+      {{#description}}
+        {{^minimum}}
+  ///
+        {{/minimum}}
+      {{/description}}
+  /// Maximum value: {{{.}}}
+    {{/maximum}}
+    {{^isNullable}}
+      {{^required}}
+        {{^defaultValue}}
+  ///
+  /// 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
+  /// source code must fall back to having a nullable type.
+  /// Consider adding a "default:" property in the specification file to hide this note.
+  ///
+        {{/defaultValue}}
+      {{/required}}
+    {{/isNullable}}
+  {{/isEnum}}
+  {{#isArray}}{{#uniqueItems}}Set{{/uniqueItems}}{{^uniqueItems}}List{{/uniqueItems}}<{{{items.dataType}}}{{#items.isNullable}}?{{/items.isNullable}}>{{/isArray}}{{^isArray}}{{{datatypeWithEnum}}}{{/isArray}}{{#isNullable}}?{{/isNullable}}{{^isNullable}}{{^required}}{{^defaultValue}}?{{/defaultValue}}{{/required}}{{/isNullable}} {{{name}}};
+
+{{/vars}}
+  @override
+  bool operator ==(Object other) => identical(this, other) || other is {{{classname}}} &&
+  {{#vars}}
+    {{#isMap}}_deepEquality.equals(other.{{{name}}}, {{{name}}}){{/isMap}}{{^isMap}}{{#isArray}}_deepEquality.equals(other.{{{name}}}, {{{name}}}){{/isArray}}{{^isArray}}other.{{{name}}} == {{{name}}}{{/isArray}}{{/isMap}}{{^-last}} &&{{/-last}}{{#-last}};{{/-last}}
+  {{/vars}}
+
+  @override
+  int get hashCode =>
+    // ignore: unnecessary_parenthesis
+  {{#vars}}
+    ({{#isNullable}}{{{name}}} == null ? 0 : {{/isNullable}}{{^isNullable}}{{^required}}{{^defaultValue}}{{{name}}} == null ? 0 : {{/defaultValue}}{{/required}}{{/isNullable}}{{{name}}}{{#isNullable}}!{{/isNullable}}{{^isNullable}}{{^required}}{{^defaultValue}}!{{/defaultValue}}{{/required}}{{/isNullable}}.hashCode){{^-last}} +{{/-last}}{{#-last}};{{/-last}}
+  {{/vars}}
+
+  @override
+  String toString() => '{{{classname}}}[{{#vars}}{{{name}}}=${{{name}}}{{^-last}}, {{/-last}}{{/vars}}]';
+
+  Map<String, dynamic> toJson() {
+    final json = <String, dynamic>{};
+  {{#vars}}
+    {{#isNullable}}
+    if (this.{{{name}}} != null) {
+    {{/isNullable}}
+    {{^isNullable}}
+      {{^required}}
+        {{^defaultValue}}
+    if (this.{{{name}}} != null) {
+        {{/defaultValue}}
+      {{/required}}
+    {{/isNullable}}
+    {{#isDateTime}}
+      {{#pattern}}
+      json[r'{{{baseName}}}'] = _isEpochMarker(r'{{{pattern}}}')
+        ? this.{{{name}}}{{#isNullable}}!{{/isNullable}}{{^isNullable}}{{^required}}{{^defaultValue}}!{{/defaultValue}}{{/required}}{{/isNullable}}.millisecondsSinceEpoch
+        : this.{{{name}}}{{#isNullable}}!{{/isNullable}}{{^isNullable}}{{^required}}{{^defaultValue}}!{{/defaultValue}}{{/required}}{{/isNullable}}.toUtc().toIso8601String();
+      {{/pattern}}
+      {{^pattern}}
+      json[r'{{{baseName}}}'] = this.{{{name}}}{{#isNullable}}!{{/isNullable}}{{^isNullable}}{{^required}}{{^defaultValue}}!{{/defaultValue}}{{/required}}{{/isNullable}}.toUtc().toIso8601String();
+      {{/pattern}}
+    {{/isDateTime}}
+    {{#isDate}}
+      {{#pattern}}
+      json[r'{{{baseName}}}'] = _isEpochMarker(r'{{{pattern}}}')
+        ? this.{{{name}}}{{#isNullable}}!{{/isNullable}}{{^isNullable}}{{^required}}{{^defaultValue}}!{{/defaultValue}}{{/required}}{{/isNullable}}.millisecondsSinceEpoch
+        : _dateFormatter.format(this.{{{name}}}{{#isNullable}}!{{/isNullable}}{{^isNullable}}{{^required}}{{^defaultValue}}!{{/defaultValue}}{{/required}}{{/isNullable}}.toUtc());
+      {{/pattern}}
+      {{^pattern}}
+      json[r'{{{baseName}}}'] = _dateFormatter.format(this.{{{name}}}{{#isNullable}}!{{/isNullable}}{{^isNullable}}{{^required}}{{^defaultValue}}!{{/defaultValue}}{{/required}}{{/isNullable}}.toUtc());
+      {{/pattern}}
+    {{/isDate}}
+    {{^isDateTime}}
+      {{^isDate}}
+      json[r'{{{baseName}}}'] = this.{{{name}}}{{#isArray}}{{#uniqueItems}}{{#isNullable}}!{{/isNullable}}.toList(growable: false){{/uniqueItems}}{{/isArray}};
+      {{/isDate}}
+    {{/isDateTime}}
+    {{#isNullable}}
+    } else {
+    //  json[r'{{{baseName}}}'] = null;
+    }
+    {{/isNullable}}
+    {{^isNullable}}
+      {{^required}}
+        {{^defaultValue}}
+    } else {
+    //  json[r'{{{baseName}}}'] = null;
+    }
+        {{/defaultValue}}
+      {{/required}}
+    {{/isNullable}}
+  {{/vars}}
+    return json;
+  }
+
+  /// Returns a new [{{{classname}}}] instance and imports its values from
+  /// [value] if it's a [Map], null otherwise.
+  // ignore: prefer_constructors_over_static_methods
+  static {{{classname}}}? fromJson(dynamic value) {
+    upgradeDto(value, "{{{classname}}}");
+    if (value is Map) {
+      final json = value.cast<String, dynamic>();
+
+      return {{{classname}}}(
+  {{#vars}}
+    {{#isDateTime}}
+        {{{name}}}: mapDateTime(json, r'{{{baseName}}}', r'{{{pattern}}}'){{#required}}{{^isNullable}}!{{/isNullable}}{{/required}}{{^required}}{{#defaultValue}} ?? {{{.}}}{{/defaultValue}}{{/required}},
+    {{/isDateTime}}
+    {{#isDate}}
+        {{{name}}}: mapDateTime(json, r'{{{baseName}}}', r'{{{pattern}}}'){{#required}}{{^isNullable}}!{{/isNullable}}{{/required}}{{^required}}{{#defaultValue}} ?? {{{.}}}{{/defaultValue}}{{/required}},
+    {{/isDate}}
+    {{^isDateTime}}
+      {{^isDate}}
+        {{#complexType}}
+          {{#isArray}}
+            {{#items.isArray}}
+        {{{name}}}: json[r'{{{baseName}}}'] is List
+          ? (json[r'{{{baseName}}}'] as List).map((e) =>
+              {{#items.complexType}}
+              {{items.complexType}}.listFromJson(json[r'{{{baseName}}}']){{#uniqueItems}}.toSet(){{/uniqueItems}}
+              {{/items.complexType}}
+              {{^items.complexType}}
+              e == null ? {{#items.isNullable}}null{{/items.isNullable}}{{^items.isNullable}}const  <{{items.items.dataType}}>[]{{/items.isNullable}} : (e as List).cast<{{items.items.dataType}}>()
+              {{/items.complexType}}
+            ).toList()
+          :  {{#isNullable}}null{{/isNullable}}{{^isNullable}}const []{{/isNullable}},
+            {{/items.isArray}}
+            {{^items.isArray}}
+        {{{name}}}: {{{complexType}}}.listFromJson(json[r'{{{baseName}}}']){{#uniqueItems}}.toSet(){{/uniqueItems}},
+            {{/items.isArray}}
+          {{/isArray}}
+          {{^isArray}}
+            {{#isMap}}
+              {{#items.isArray}}
+        {{{name}}}: json[r'{{{baseName}}}'] == null
+          ? {{#defaultValue}}{{{.}}}{{/defaultValue}}{{^defaultValue}}null{{/defaultValue}}
+                {{#items.complexType}}
+            : {{items.complexType}}.mapListFromJson(json[r'{{{baseName}}}']),
+                {{/items.complexType}}
+                {{^items.complexType}}
+            : mapCastOfType<String, List>(json, r'{{{baseName}}}'),
+                {{/items.complexType}}
+              {{/items.isArray}}
+              {{^items.isArray}}
+                {{#items.isMap}}
+                  {{#items.complexType}}
+        {{{name}}}: {{items.complexType}}.mapFromJson(json[r'{{{baseName}}}']),
+                  {{/items.complexType}}
+                  {{^items.complexType}}
+        {{{name}}}: mapCastOfType<String, dynamic>(json, r'{{{baseName}}}'){{#required}}{{^isNullable}}!{{/isNullable}}{{/required}}{{^required}}{{#defaultValue}} ?? {{{.}}}{{/defaultValue}}{{/required}},
+                  {{/items.complexType}}
+                {{/items.isMap}}
+                {{^items.isMap}}
+                  {{#items.complexType}}
+        {{{name}}}: {{{items.complexType}}}.mapFromJson(json[r'{{{baseName}}}']),
+                  {{/items.complexType}}
+                  {{^items.complexType}}
+        {{{name}}}: mapCastOfType<String, {{items.dataType}}>(json, r'{{{baseName}}}'){{#required}}{{^isNullable}}!{{/isNullable}}{{/required}}{{^required}}{{#defaultValue}} ?? {{{.}}}{{/defaultValue}}{{/required}},
+                  {{/items.complexType}}
+                {{/items.isMap}}
+              {{/items.isArray}}
+            {{/isMap}}
+            {{^isMap}}
+              {{#isBinary}}
+        {{{name}}}: null, // No support for decoding binary content from JSON
+              {{/isBinary}}
+              {{^isBinary}}
+        {{{name}}}: {{{complexType}}}.fromJson(json[r'{{{baseName}}}']){{#required}}{{^isNullable}}!{{/isNullable}}{{/required}}{{^required}}{{#defaultValue}} ?? {{{.}}}{{/defaultValue}}{{/required}},
+              {{/isBinary}}
+            {{/isMap}}
+          {{/isArray}}
+        {{/complexType}}
+        {{^complexType}}
+          {{#isArray}}
+            {{#isEnum}}
+        {{{name}}}: {{{items.datatypeWithEnum}}}.listFromJson(json[r'{{{baseName}}}']){{#uniqueItems}}.toSet(){{/uniqueItems}},
+            {{/isEnum}}
+            {{^isEnum}}
+        {{{name}}}: json[r'{{{baseName}}}'] is Iterable
+            ? (json[r'{{{baseName}}}'] as Iterable).cast<{{{items.datatype}}}>().{{#uniqueItems}}toSet(){{/uniqueItems}}{{^uniqueItems}}toList(growable: false){{/uniqueItems}}
+            : {{#defaultValue}}{{{.}}}{{/defaultValue}}{{^defaultValue}}null{{/defaultValue}},
+            {{/isEnum}}
+          {{/isArray}}
+          {{^isArray}}
+            {{#isMap}}
+        {{{name}}}: mapCastOfType<String, {{{items.datatype}}}>(json, r'{{{baseName}}}'){{#required}}{{^isNullable}}!{{/isNullable}}{{/required}}{{^required}}{{#defaultValue}} ?? {{{.}}}{{/defaultValue}}{{/required}},
+            {{/isMap}}
+            {{^isMap}}
+              {{#isNumber}}
+        {{{name}}}: {{#isNullable}}json[r'{{{baseName}}}'] == null
+            ? {{#defaultValue}}{{{.}}}{{/defaultValue}}{{^defaultValue}}null{{/defaultValue}}
+            : {{/isNullable}}{{{datatypeWithEnum}}}.parse('${json[r'{{{baseName}}}']}'),
+              {{/isNumber}}
+              {{#isDouble}}
+        {{{name}}}: (mapValueOfType<num>(json, r'{{{baseName}}}'){{#required}}{{^isNullable}}!{{/isNullable}}{{/required}}{{^required}}{{#defaultValue}} ?? {{{.}}}{{/defaultValue}}{{/required}}){{#isNullable}}?{{/isNullable}}.toDouble(),
+              {{/isDouble}}
+              {{^isDouble}}
+              {{^isNumber}}
+                {{^isEnum}}
+        {{{name}}}: mapValueOfType<{{{datatypeWithEnum}}}>(json, r'{{{baseName}}}'){{#required}}{{^isNullable}}!{{/isNullable}}{{/required}}{{^required}}{{#defaultValue}} ?? {{{.}}}{{/defaultValue}}{{/required}},
+                {{/isEnum}}
+                {{#isEnum}}
+        {{{name}}}: {{{enumName}}}.fromJson(json[r'{{{baseName}}}']){{#required}}{{^isNullable}}!{{/isNullable}}{{/required}}{{^required}}{{#defaultValue}} ?? {{{.}}}{{/defaultValue}}{{/required}},
+                {{/isEnum}}
+              {{/isNumber}}
+              {{/isDouble}}
+            {{/isMap}}
+          {{/isArray}}
+        {{/complexType}}
+      {{/isDate}}
+    {{/isDateTime}}
+  {{/vars}}
+      );
+    }
+    return null;
+  }
+
+  static List<{{{classname}}}> listFromJson(dynamic json, {bool growable = false,}) {
+    final result = <{{{classname}}}>[];
+    if (json is List && json.isNotEmpty) {
+      for (final row in json) {
+        final value = {{{classname}}}.fromJson(row);
+        if (value != null) {
+          result.add(value);
+        }
+      }
+    }
+    return result.toList(growable: growable);
+  }
+
+  static Map<String, {{{classname}}}> mapFromJson(dynamic json) {
+    final map = <String, {{{classname}}}>{};
+    if (json is Map && json.isNotEmpty) {
+      json = json.cast<String, dynamic>(); // ignore: parameter_assignments
+      for (final entry in json.entries) {
+        final value = {{{classname}}}.fromJson(entry.value);
+        if (value != null) {
+          map[entry.key] = value;
+        }
+      }
+    }
+    return map;
+  }
+
+  // maps a json object with a list of {{{classname}}}-objects as value to a dart map
+  static Map<String, List<{{{classname}}}>> mapListFromJson(dynamic json, {bool growable = false,}) {
+    final map = <String, List<{{{classname}}}>>{};
+    if (json is Map && json.isNotEmpty) {
+      // ignore: parameter_assignments
+      json = json.cast<String, dynamic>();
+      for (final entry in json.entries) {
+        map[entry.key] = {{{classname}}}.listFromJson(entry.value, growable: growable,);
+      }
+    }
+    return map;
+  }
+
+  /// The list of required keys that must be present in a JSON.
+  static const requiredKeys = <String>{
+{{#vars}}
+  {{#required}}
+    '{{{baseName}}}',
+  {{/required}}
+{{/vars}}
+  };
+}
+{{#vars}}
+    {{^isModel}}
+    {{#isEnum}}
+        {{^isContainer}}
+
+{{>serialization/native/native_enum_inline}}
+        {{/isContainer}}
+        {{#isContainer}}
+            {{#mostInnerItems}}
+
+{{>serialization/native/native_enum_inline}}
+            {{/mostInnerItems}}
+        {{/isContainer}}
+    {{/isEnum}}
+    {{/isModel}}
+{{/vars}}

open-api/templates/mobile/serialization/native/native_class.mustache.patch

@@ -0,0 +1,60 @@
+--- native_class.mustache	2025-07-01 08:29:23.968133163 +0800
++++ native_class_temp.mustache	2025-07-01 08:29:44.225850583 +0800
+@@ -91,14 +91,14 @@
+     {{/isDateTime}}
+     {{#isNullable}}
+     } else {
+-      json[r'{{{baseName}}}'] = null;
++    //  json[r'{{{baseName}}}'] = null;
+     }
+     {{/isNullable}}
+     {{^isNullable}}
+       {{^required}}
+         {{^defaultValue}}
+     } else {
+-      json[r'{{{baseName}}}'] = null;
++    //  json[r'{{{baseName}}}'] = null;
+     }
+         {{/defaultValue}}
+       {{/required}}
+@@ -111,20 +111,10 @@
+   /// [value] if it's a [Map], null otherwise.
+   // ignore: prefer_constructors_over_static_methods
+   static {{{classname}}}? fromJson(dynamic value) {
++    upgradeDto(value, "{{{classname}}}");
+     if (value is Map) {
+       final json = value.cast<String, dynamic>();
+
+-      // Ensure that the map contains the required keys.
+-      // Note 1: the values aren't checked for validity beyond being non-null.
+-      // Note 2: this code is stripped in release mode!
+-      assert(() {
+-        requiredKeys.forEach((key) {
+-          assert(json.containsKey(key), 'Required key "{{{classname}}}[$key]" is missing from JSON.');
+-          assert(json[key] != null, 'Required key "{{{classname}}}[$key]" has a null value in JSON.');
+-        });
+-        return true;
+-      }());
+-
+       return {{{classname}}}(
+   {{#vars}}
+     {{#isDateTime}}
+@@ -215,6 +205,10 @@
+             ? {{#defaultValue}}{{{.}}}{{/defaultValue}}{{^defaultValue}}null{{/defaultValue}}
+             : {{/isNullable}}{{{datatypeWithEnum}}}.parse('${json[r'{{{baseName}}}']}'),
+               {{/isNumber}}
++              {{#isDouble}}
++        {{{name}}}: (mapValueOfType<num>(json, r'{{{baseName}}}'){{#required}}{{^isNullable}}!{{/isNullable}}{{/required}}{{^required}}{{#defaultValue}} ?? {{{.}}}{{/defaultValue}}{{/required}}){{#isNullable}}?{{/isNullable}}.toDouble(),
++              {{/isDouble}}
++              {{^isDouble}}
+               {{^isNumber}}
+                 {{^isEnum}}
+         {{{name}}}: mapValueOfType<{{{datatypeWithEnum}}}>(json, r'{{{baseName}}}'){{#required}}{{^isNullable}}!{{/isNullable}}{{/required}}{{^required}}{{#defaultValue}} ?? {{{.}}}{{/defaultValue}}{{/required}},
+@@ -223,6 +217,7 @@
+         {{{name}}}: {{{enumName}}}.fromJson(json[r'{{{baseName}}}']){{#required}}{{^isNullable}}!{{/isNullable}}{{/required}}{{^required}}{{#defaultValue}} ?? {{{.}}}{{/defaultValue}}{{/required}},
+                 {{/isEnum}}
+               {{/isNumber}}
++              {{/isDouble}}
+             {{/isMap}}
+           {{/isArray}}
+         {{/complexType}}

open-api/templates/mobile/serialization/native/native_class_nullable_items_in_arrays.patch

@@ -0,0 +1,13 @@
+diff --git a/open-api/templates/mobile/serialization/native/native_class.mustache b/open-api/templates/mobile/serialization/native/native_class.mustache
+index 9a7b1439b..9f40d5b0b 100644
+--- a/open-api/templates/mobile/serialization/native/native_class.mustache
++++ b/open-api/templates/mobile/serialization/native/native_class.mustache
+@@ -32,7 +32,7 @@ class {{{classname}}} {
+       {{/required}}
+     {{/isNullable}}
+   {{/isEnum}}
+-  {{{datatypeWithEnum}}}{{#isNullable}}?{{/isNullable}}{{^isNullable}}{{^required}}{{^defaultValue}}?{{/defaultValue}}{{/required}}{{/isNullable}} {{{name}}};
++  {{#isArray}}{{#uniqueItems}}Set{{/uniqueItems}}{{^uniqueItems}}List{{/uniqueItems}}<{{{items.dataType}}}{{#items.isNullable}}?{{/items.isNullable}}>{{/isArray}}{{^isArray}}{{{datatypeWithEnum}}}{{/isArray}}{{#isNullable}}?{{/isNullable}}{{^isNullable}}{{^required}}{{^defaultValue}}?{{/defaultValue}}{{/required}}{{/isNullable}} {{{name}}};
+ 
+ {{/vars}}
+   @override

open-api/typescript-sdk/.npmignore

@@ -0,0 +1,3 @@
+package-lock.json
+tsconfig.json
+src/

open-api/typescript-sdk/.nvmrc

@@ -0,0 +1 @@
+24.13.0

open-api/typescript-sdk/README.md

@@ -0,0 +1,26 @@
+# @immich/sdk
+
+A TypeScript SDK for interfacing with the [Immich](https://immich.app/) API.
+
+## Install
+
+```bash
+npm i --save @immich/sdk
+```
+
+## Usage
+
+For a more detailed example, check out the [`@immich/cli`](https://github.com/immich-app/immich/tree/main/cli).
+
+```typescript
+import { getAllAlbums, getMyUser, init } from "@immich/sdk";
+
+const API_KEY = "<API_KEY>"; // process.env.IMMICH_API_KEY
+
+init({ baseUrl: "https://demo.immich.app/api", apiKey: API_KEY });
+
+const user = await getMyUser();
+const albums = await getAllAlbums({});
+
+console.log({ user, albums });
+```

open-api/typescript-sdk/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@immich/sdk",
+  "version": "2.5.2",
+  "description": "Auto-generated TypeScript SDK for the Immich API",
+  "type": "module",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "license": "GNU Affero General Public License version 3",
+  "dependencies": {
+    "@oazapfts/runtime": "^1.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.9",
+    "typescript": "^5.3.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/immich-app/immich.git",
+    "directory": "open-api/typescript-sdk"
+  },
+  "volta": {
+    "node": "24.13.0"
+  }
+}

open-api/typescript-sdk/src/fetch-errors.ts

@@ -0,0 +1,15 @@
+import { HttpError } from '@oazapfts/runtime';
+
+export interface ApiExceptionResponse {
+  message: string;
+  error?: string;
+  statusCode: number;
+}
+
+export interface ApiHttpError extends HttpError {
+  data: ApiExceptionResponse;
+}
+
+export function isHttpError(error: unknown): error is ApiHttpError {
+  return error instanceof HttpError;
+}

open-api/typescript-sdk/src/index.ts

@@ -0,0 +1,62 @@
+import { defaults } from './fetch-client.js';
+
+export * from './fetch-client.js';
+export * from './fetch-errors.js';
+
+export interface InitOptions {
+  baseUrl: string;
+  apiKey: string;
+  headers?: Record<string, string>;
+}
+
+export const init = ({ baseUrl, apiKey, headers }: InitOptions) => {
+  setBaseUrl(baseUrl);
+  setApiKey(apiKey);
+  if (headers) {
+    setHeaders(headers);
+  }
+};
+
+export const getBaseUrl = () => defaults.baseUrl;
+
+export const setBaseUrl = (baseUrl: string) => {
+  defaults.baseUrl = baseUrl;
+};
+
+export const setApiKey = (apiKey: string) => {
+  defaults.headers = defaults.headers || {};
+  defaults.headers['x-api-key'] = apiKey;
+};
+
+export const setHeader = (key: string, value: string) => {
+  assertNoApiKey(key);
+  defaults.headers = defaults.headers || {};
+  defaults.headers[key] = value;
+};
+
+export const setHeaders = (headers: Record<string, string>) => {
+  defaults.headers = defaults.headers || {};
+  for (const [key, value] of Object.entries(headers)) {
+    assertNoApiKey(key);
+    defaults.headers[key] = value;
+  }
+};
+
+const assertNoApiKey = (headerKey: string) => {
+  if (headerKey.toLowerCase() === 'x-api-key') {
+    throw new Error('The API key header can only be set using setApiKey().');
+  }
+};
+
+export const getAssetOriginalPath = (id: string) => `/assets/${id}/original`;
+
+export const getAssetThumbnailPath = (id: string) => `/assets/${id}/thumbnail`;
+
+export const getAssetPlaybackPath = (id: string) =>
+  `/assets/${id}/video/playback`;
+
+export const getUserProfileImagePath = (userId: string) =>
+  `/users/${userId}/profile-image`;
+
+export const getPeopleThumbnailPath = (personId: string) =>
+  `/people/${personId}/thumbnail`;

open-api/typescript-sdk/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "build",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["esnext", "dom"]
+  },
+  "include": ["src/**/*.ts"]
+}