From fb607099e2d8adb3899dda6c7f16ec8a892481bb Mon Sep 17 00:00:00 2001
From: Mikal Stordal <mikalstordal@gmail.com>
Date: Thu, 26 Dec 2024 01:10:51 +0100
Subject: [PATCH] feat: more query options for the APIv3 random image metadata
 endpoint

---
 .../API/v3/Controllers/ImageController.cs     | 29 +++++++++++++++++--
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/Shoko.Server/API/v3/Controllers/ImageController.cs b/Shoko.Server/API/v3/Controllers/ImageController.cs
index cc4d15c82..93e9130ff 100644
--- a/Shoko.Server/API/v3/Controllers/ImageController.cs
+++ b/Shoko.Server/API/v3/Controllers/ImageController.cs
@@ -1,11 +1,16 @@
+using System.Collections.Generic;
 using System.ComponentModel.DataAnnotations;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.Mvc.ModelBinding;
+using Shoko.Commons.Extensions;
 using Shoko.Models.Enums;
 using Shoko.Plugin.Abstractions.Enums;
 using Shoko.Server.API.Annotations;
+using Shoko.Server.API.ModelBinders;
+using Shoko.Server.API.v3.Helpers;
 using Shoko.Server.API.v3.Models.Common;
+using Shoko.Server.API.v3.Models.Shoko;
 using Shoko.Server.Repositories;
 using Shoko.Server.Settings;
 using Shoko.Server.Utilities;
@@ -143,12 +148,20 @@ public ActionResult GetRandomImageForType([FromRoute] Image.ImageType imageType)
     /// Returns the metadata for a random image for the <paramref name="imageType"/>.
     /// </summary>
     /// <param name="imageType">Poster, Backdrop, Banner, Thumb</param>
+    /// <param name="includeRestricted">Include or exclude restricted images</param>
+    /// <param name="seriesType">Series types to include in the search</param>
+    /// <param name="maxAttempts">Maximum number of attempts to find a valid image</param>
     /// <returns>200 on found, 400 if the type or source are invalid</returns>
     [HttpGet("Random/{imageType}/Metadata")]
     [ProducesResponseType(typeof(Image), 200)]
     [ProducesResponseType(400)]
     [ProducesResponseType(500)]
-    public ActionResult<Image> GetRandomImageMetadataForType([FromRoute] Image.ImageType imageType)
+    public ActionResult<Image> GetRandomImageMetadataForType(
+        [FromRoute] Image.ImageType imageType,
+        [FromQuery] IncludeOnlyFilter includeRestricted = IncludeOnlyFilter.False,
+        [FromQuery, ModelBinder(typeof(CommaDelimitedModelBinder))] HashSet<SeriesType> seriesType = null,
+        [FromQuery, Range(0, 100)] int maxAttempts = 5
+    )
     {
         if (imageType == Image.ImageType.Avatar)
             return ValidationProblem("Unsupported image type for random image.", "imageType");
@@ -171,13 +184,23 @@ public ActionResult<Image> GetRandomImageMetadataForType([FromRoute] Image.Image
 
             var image = new Image(metadata);
             var series = ImageUtils.GetFirstSeriesForImage(metadata);
-            if (series == null || (series.AniDB_Anime?.IsRestricted ?? false))
+            if (series.AniDB_Anime is not { } anime)
+                continue;
+
+            if (includeRestricted != IncludeOnlyFilter.True)
+            {
+                var onlyRestricted = includeRestricted is IncludeOnlyFilter.Only;
+                if (onlyRestricted != anime.IsRestricted)
+                    continue;
+            }
+
+            if (seriesType is not null && !seriesType.Contains(anime.GetAnimeTypeEnum().ToAniDBSeriesType()))
                 continue;
 
             image.Series = new(series.AnimeSeriesID, series.PreferredTitle);
 
             return image;
-        } while (tries++ < 5);
+        } while (tries++ < maxAttempts);
 
         return InternalError("Unable to find a random image to send.");
     }