From f01da02b58ffd50878616ac210ed1929a0fb678e Mon Sep 17 00:00:00 2001
From: abdulmohsen <admin@arabcoders.org>
Date: Sun, 9 Jun 2024 16:37:54 +0300
Subject: [PATCH] Mismatched API: return an StateEntity object instead of
 custom responses.

---
 .../pages/backend/[backend]/mismatched.vue    |  11 +-
 src/API/Backend/Mismatched.php                | 319 +++++++++++++++++-
 src/Backends/Common/ClientInterface.php       |   2 +-
 src/Backends/Jellyfin/Action/GetLibrary.php   |  72 ++--
 src/Backends/Jellyfin/Action/Import.php       |   1 -
 src/Backends/Plex/Action/GetLibrary.php       |  62 ++--
 src/Libs/Options.php                          |   2 +-
 7 files changed, 411 insertions(+), 58 deletions(-)

diff --git a/frontend/pages/backend/[backend]/mismatched.vue b/frontend/pages/backend/[backend]/mismatched.vue
index 3cd00411..c4841775 100644
--- a/frontend/pages/backend/[backend]/mismatched.vue
+++ b/frontend/pages/backend/[backend]/mismatched.vue
@@ -82,7 +82,8 @@
           <div class="card">
             <header class="card-header">
               <p class="card-header-title is-text-overflow">
-                <NuxtLink target="_blank" :to="item.webUrl ?? item.url">{{ item.title }}</NuxtLink>
+                <NuxtLink target="_blank" :to="item.webUrl" v-if="item.webUrl" v-text="item.title"/>
+                <span v-else>{{ item.title }}</span>
               </p>
               <div class="card-header-icon" @click="item.showItem = !item.showItem">
                 <span class="icon has-tooltip">
@@ -107,7 +108,11 @@
                 </span>
                 </div>
                 <div class="column is-12" v-if="item.path">
-                  <strong>Path:</strong> {{ item.path }}
+                  <div class="is-text-overflow">
+                    <span class="icon"><i class="fas fa-file"></i></span>
+                    <span class="is-hidden-mobile">File:&nbsp;</span>
+                    <NuxtLink :to="makeSearchLink('path',item.path)" v-text="item.path"/>
+                  </div>
                 </div>
               </div>
             </div>
@@ -143,7 +148,7 @@
 </template>
 
 <script setup>
-import {notification} from "~/utils/index.js";
+import {makeSearchLink, notification} from "~/utils/index.js";
 import {useStorage} from "@vueuse/core";
 
 const backend = useRoute().params.backend
diff --git a/src/API/Backend/Mismatched.php b/src/API/Backend/Mismatched.php
index 602abba7..50e52f2b 100644
--- a/src/API/Backend/Mismatched.php
+++ b/src/API/Backend/Mismatched.php
@@ -5,20 +5,51 @@ declare(strict_types=1);
 namespace App\API\Backend;
 
 use App\API\Backend\Index as backendIndex;
-use App\Commands\Backend\Library\MismatchCommand;
+use App\Backends\Common\ClientInterface as iClient;
 use App\Libs\Attributes\Route\Get;
 use App\Libs\DataUtil;
+use App\Libs\Entity\StateInterface as iState;
 use App\Libs\Exceptions\RuntimeException;
 use App\Libs\HTTP_STATUS;
 use App\Libs\Options;
 use App\Libs\Traits\APITraits;
 use Psr\Http\Message\ResponseInterface as iResponse;
 use Psr\Http\Message\ServerRequestInterface as iRequest;
+use Throwable;
 
 final class Mismatched
 {
     use APITraits;
 
+    public const array METHODS = [
+        'similarity',
+        'levenshtein',
+    ];
+    public const float DEFAULT_PERCENT = 50.0;
+    public const array REMOVED_CHARS = [
+        '?',
+        ':',
+        '(',
+        '[',
+        ']',
+        ')',
+        ',',
+        '|',
+        '%',
+        '.',
+        '–',
+        '-',
+        "'",
+        '"',
+        '+',
+        '/',
+        ';',
+        '&',
+        '_',
+        '!',
+        '*',
+    ];
+
     #[Get(backendIndex::URL . '/{name:backend}/mismatched[/[{id}[/]]]', name: 'backend.mismatched')]
     public function __invoke(iRequest $request, array $args = []): iResponse
     {
@@ -34,15 +65,22 @@ final class Mismatched
             $backendOpts = ag_set($backendOpts, 'client.timeout', (float)$params->get('timeout'));
         }
 
-        if ($params->get('raw')) {
-            $opts[Options::RAW_RESPONSE] = true;
-        }
+        $includeRaw = $params->get('raw') || $params->get(Options::RAW_RESPONSE);
 
-        $percentage = (float)$params->get('percentage', MismatchCommand::DEFAULT_PERCENT);
-        $method = $params->get('method', MismatchCommand::METHODS[0]);
+        $opts[Options::RAW_RESPONSE] = true;
 
-        if (false === in_array($method, MismatchCommand::METHODS, true)) {
-            return api_error('Invalid comparison method.', HTTP_STATUS::HTTP_BAD_REQUEST);
+        $opts[Options::MISMATCH_DEEP_SCAN] = true;
+        $opts[Options::NO_LOGGING] = true;
+
+        $percentage = (float)$params->get('percentage', self::DEFAULT_PERCENT);
+        $method = $params->get('method', self::METHODS[0]);
+
+        if (false === in_array($method, self::METHODS, true)) {
+            return api_error(r("Invalid comparison method '{method}'. Expecting '{methods}'", [
+                'method' => $method,
+                'methods' => implode(", ", self::METHODS),
+
+            ]), HTTP_STATUS::HTTP_BAD_REQUEST);
         }
 
         try {
@@ -65,15 +103,278 @@ final class Mismatched
 
         foreach ($ids as $libraryId) {
             foreach ($client->getLibrary(id: $libraryId, opts: $opts) as $item) {
-                $processed = MismatchCommand::compare(item: $item, method: $method);
+                $processed = $this->compare(client: $client, item: $item, method: $method);
 
                 if (empty($processed) || $processed['percent'] >= $percentage) {
                     continue;
                 }
 
+                if (false === $includeRaw && ag_exists($processed, Options::RAW_RESPONSE)) {
+                    unset($processed[Options::RAW_RESPONSE]);
+                }
+
                 $list[] = $processed;
             }
         }
+
         return api_response(HTTP_STATUS::HTTP_OK, $list);
     }
+
+    protected function compare(iClient $client, array $item, string $method): array
+    {
+        if (empty($item)) {
+            return [];
+        }
+
+        if (null === ($paths = ag($item, 'match.paths', [])) || empty($paths)) {
+            return [];
+        }
+
+        if (null === ($titles = ag($item, 'match.titles', [])) || empty($titles)) {
+            return [];
+        }
+
+        try {
+            $builder = $client->toEntity($item[Options::RAW_RESPONSE])->getAll();
+        } catch (Throwable) {
+            // -- we likely encountered unexpected content type.
+            return [];
+        }
+
+        if (count($item['guids']) < 1) {
+            $item['guids'] = 'None';
+        }
+
+        $toLower = fn(string $text, bool $isASCII = false) => trim($isASCII ? strtolower($text) : mb_strtolower($text));
+
+        $builder['percent'] = $percent = 0.0;
+        $builder['matches'] = [];
+
+        foreach ($paths as $path) {
+            $pathFull = ag($path, 'full');
+            $pathShort = ag($path, 'short');
+
+            if (empty($pathFull) || empty($pathShort)) {
+                continue;
+            }
+
+            foreach ($titles as $title) {
+                $isASCII = mb_detect_encoding($pathShort, 'ASCII') && mb_detect_encoding($title, 'ASCII');
+
+                $title = $toLower(self::formatName(name: $title), isASCII: $isASCII);
+                $pathShort = $toLower(self::formatName(name: $pathShort), isASCII: $isASCII);
+
+                if (1 === preg_match('/\((\d{4})\)/', basename($pathFull), $match)) {
+                    $withYear = true;
+                    if (ag($item, 'year') && false === str_contains($title, (string)ag($item, 'year'))) {
+                        $title .= ' ' . ag($item, 'year');
+                    }
+                } else {
+                    $withYear = false;
+                }
+
+                if (true === str_starts_with($pathShort, $title)) {
+                    $percent = 100.0;
+                }
+
+                if (true === $isASCII) {
+                    similar_text($pathShort, $title, $similarity);
+                    $levenshtein = levenshtein($pathShort, $title);
+                } else {
+                    self::mb_similar_text($pathShort, $title, $similarity);
+                    $levenshtein = self::mb_levenshtein($pathShort, $title);
+                }
+
+                $levenshtein = self::toPercentage($levenshtein, $pathShort, $title);
+
+                switch ($method) {
+                    default:
+                    case 'similarity':
+                        if ($similarity > $percent) {
+                            $percent = $similarity;
+                        }
+                        break;
+                    case 'levenshtein':
+                        if ($similarity > $percent) {
+                            $percent = $levenshtein;
+                        }
+                        break;
+                }
+
+                if (round($percent, 3) > $builder['percent']) {
+                    $builder['percent'] = round($percent, 3);
+                }
+
+                $builder['matches'][] = [
+                    'path' => $pathShort,
+                    'title' => $title,
+                    'type' => $isASCII ? 'ascii' : 'unicode',
+                    'methods' => [
+                        'similarity' => round($similarity, 3),
+                        'levenshtein' => round($levenshtein, 3),
+                        'startWith' => str_starts_with($pathShort, $title),
+                    ],
+                    'year' => [
+                        'inPath' => $withYear,
+                        'parsed' => isset($match[1]) ? (int)$match[1] : 'No',
+                        'source' => ag($item, 'year', 'No'),
+                    ],
+                ];
+            }
+        }
+
+        if (count($paths) <= 2 && null !== ($paths[0]['full'] ?? null)) {
+            $builder['path'] = $paths[0]['full'];
+        }
+
+        if (null !== ($url = ag($item, 'url'))) {
+            $builder['url'] = $url;
+        }
+
+        if (null !== ($webUrl = ag($item, 'webUrl'))) {
+            $builder['webUrl'] = $webUrl;
+        }
+
+        return ag_set($builder, iState::COLUMN_META_LIBRARY, ag($item, iState::COLUMN_META_LIBRARY));
+    }
+
+    /**
+     * Formats the given name.
+     *
+     * @param string $name The name to format.
+     *
+     * @return string The formatted name.
+     */
+    public static function formatName(string $name): string
+    {
+        $name = preg_replace('#[\[{].+?[]}]#', '', $name);
+        return trim(preg_replace('/\s+/', ' ', str_replace(self::REMOVED_CHARS, ' ', $name)));
+    }
+
+    /**
+     * Implementation of `mb_similar_text()`.
+     *
+     * (c) Antal Áron <antalaron@antalaron.hu>
+     *
+     * @see http://php.net/manual/en/function.similar-text.php
+     * @see http://locutus.io/php/strings/similar_text/
+     *
+     * @param string $str1
+     * @param string $str2
+     * @param float|null $percent
+     *
+     * @return int
+     */
+    private function mb_similar_text(string $str1, string $str2, float|null &$percent = null): int
+    {
+        if (0 === mb_strlen($str1) + mb_strlen($str2)) {
+            $percent = 0.0;
+
+            return 0;
+        }
+
+        $pos1 = $pos2 = $max = 0;
+        $l1 = mb_strlen($str1);
+        $l2 = mb_strlen($str2);
+
+        for ($p = 0; $p < $l1; ++$p) {
+            for ($q = 0; $q < $l2; ++$q) {
+                /** @noinspection LoopWhichDoesNotLoopInspection */
+                /** @noinspection MissingOrEmptyGroupStatementInspection */
+                for (
+                    $l = 0; ($p + $l < $l1) && ($q + $l < $l2) && mb_substr($str1, $p + $l, 1) === mb_substr(
+                    $str2,
+                    $q + $l,
+                    1
+                ); ++$l
+                ) {
+                    // nothing to do
+                }
+                if ($l > $max) {
+                    $max = $l;
+                    $pos1 = $p;
+                    $pos2 = $q;
+                }
+            }
+        }
+
+        $similarity = $max;
+        if ($similarity) {
+            if ($pos1 && $pos2) {
+                $similarity += self::mb_similar_text(mb_substr($str1, 0, $pos1), mb_substr($str2, 0, $pos2));
+            }
+            if (($pos1 + $max < $l1) && ($pos2 + $max < $l2)) {
+                $similarity += self::mb_similar_text(
+                    mb_substr($str1, $pos1 + $max, $l1 - $pos1 - $max),
+                    mb_substr($str2, $pos2 + $max, $l2 - $pos2 - $max)
+                );
+            }
+        }
+
+        $percent = ($similarity * 200.0) / ($l1 + $l2);
+
+        return $similarity;
+    }
+
+    /**
+     * Implementation levenshtein distance algorithm.
+     *
+     * @param string $str1 The first string.
+     * @param string $str2 The second string.
+     *
+     * @return int The Levenshtein distance between the two strings.
+     */
+    private function mb_levenshtein(string $str1, string $str2): int
+    {
+        $length1 = mb_strlen($str1, 'UTF-8');
+        $length2 = mb_strlen($str2, 'UTF-8');
+
+        if ($length1 < $length2) {
+            return self::mb_levenshtein($str2, $str1);
+        }
+
+        if (0 === $length1) {
+            return $length2;
+        }
+
+        if ($str1 === $str2) {
+            return 0;
+        }
+
+        $prevRow = range(0, $length2);
+
+        for ($i = 0; $i < $length1; $i++) {
+            $currentRow = [];
+            $currentRow[0] = $i + 1;
+            $c1 = mb_substr($str1, $i, 1, 'UTF-8');
+
+            for ($j = 0; $j < $length2; $j++) {
+                $c2 = mb_substr($str2, $j, 1, 'UTF-8');
+                $insertions = $prevRow[$j + 1] + 1;
+                $deletions = $currentRow[$j] + 1;
+                $substitutions = $prevRow[$j] + (($c1 !== $c2) ? 1 : 0);
+                $currentRow[] = min($insertions, $deletions, $substitutions);
+            }
+
+            $prevRow = $currentRow;
+        }
+        return $prevRow[$length2];
+    }
+
+    /**
+     * How much percentage is the base value of the lengths of the strings.
+     *
+     * @param int $base The base value.
+     * @param string $str1 The first string.
+     * @param string $str2 The second string.
+     * @param bool $isASCII Whether to consider ASCII characters only. Default is false.
+     *
+     * @return float The percentage value calculated based on the base value and the lengths of the strings.
+     */
+    private function toPercentage(int $base, string $str1, string $str2, bool $isASCII = false): float
+    {
+        $length = fn(string $text) => $isASCII ? mb_strlen($text, 'UTF-8') : strlen($text);
+
+        return (1 - $base / max($length($str1), $length($str2))) * 100;
+    }
 }
diff --git a/src/Backends/Common/ClientInterface.php b/src/Backends/Common/ClientInterface.php
index e4948f8b..aa45d339 100644
--- a/src/Backends/Common/ClientInterface.php
+++ b/src/Backends/Common/ClientInterface.php
@@ -175,7 +175,7 @@ interface ClientInterface
      * @param string|int $id library id.
      * @param array $opts options.
      *
-     * @return array empty array if no items found.
+     * @return array|array<iState> empty array if no items found.
      */
     public function getLibrary(string|int $id, array $opts = []): array;
 
diff --git a/src/Backends/Jellyfin/Action/GetLibrary.php b/src/Backends/Jellyfin/Action/GetLibrary.php
index 8724ee9c..40fa20b3 100644
--- a/src/Backends/Jellyfin/Action/GetLibrary.php
+++ b/src/Backends/Jellyfin/Action/GetLibrary.php
@@ -12,15 +12,17 @@ use App\Backends\Common\Levels;
 use App\Backends\Common\Response;
 use App\Backends\Jellyfin\JellyfinActionTrait;
 use App\Backends\Jellyfin\JellyfinClient;
+use App\Libs\Entity\StateInterface as iState;
+use App\Libs\Exceptions\Backends\InvalidArgumentException;
 use App\Libs\Exceptions\Backends\RuntimeException;
 use App\Libs\Options;
 use JsonMachine\Items;
 use JsonMachine\JsonDecoder\DecodingError;
 use JsonMachine\JsonDecoder\ErrorWrappingDecoder;
 use JsonMachine\JsonDecoder\ExtJsonDecoder;
-use Psr\Log\LoggerInterface;
+use Psr\Log\LoggerInterface as iLogger;
 use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;
-use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Symfony\Contracts\HttpClient\HttpClientInterface as iHttp;
 
 /**
  * Class GetLibrary
@@ -37,10 +39,10 @@ class GetLibrary
     /**
      * Class constructor
      *
-     * @param HttpClientInterface $http The HTTP client object.
-     * @param LoggerInterface $logger The logger object.
+     * @param iHttp $http The HTTP client object.
+     * @param iLogger $logger The logger object.
      */
-    public function __construct(protected HttpClientInterface $http, protected LoggerInterface $logger)
+    public function __construct(protected iHttp $http, protected iLogger $logger)
     {
     }
 
@@ -58,7 +60,7 @@ class GetLibrary
     {
         return $this->tryResponse(
             context: $context,
-            fn: fn() => $this->action($context, $id, $opts),
+            fn: fn() => $this->action($context, $guid, $id, $opts),
             action: $this->action
         );
     }
@@ -74,8 +76,9 @@ class GetLibrary
      * @throws ExceptionInterface If the backend request fails.
      * @throws RuntimeException When the API call was not successful.
      * @throws \JsonMachine\Exception\InvalidArgumentException If the backend response is not a valid JSON.
+     * @throws InvalidArgumentException
      */
-    private function action(Context $context, string|int $id, array $opts = []): Response
+    private function action(Context $context, iGuid $guid, string|int $id, array $opts = []): Response
     {
         $libraries = $this->getBackendLibraries($context);
 
@@ -188,6 +191,10 @@ class GetLibrary
                 continue;
             }
 
+            if (false === $this->isSupportedType(ag($entity, 'Type'))) {
+                continue;
+            }
+
             $url = $context->backendUrl->withPath(
                 sprintf('/Users/%s/items/%s', $context->backendUser, ag($entity, 'Id'))
             );
@@ -200,13 +207,22 @@ class GetLibrary
                 'url' => (string)$url,
             ];
 
-            if (null !== ($indexNumberEnd = ag($entity, 'IndexNumberEnd'))) {
-                foreach (range((int)ag($entity, 'IndexNumber'), $indexNumberEnd) as $i) {
-                    $entity['IndexNumber'] = $i;
+            // -- Handle multi episode entries.
+            $indexNumber = ag($entity, 'IndexNumber');
+            $indexNumberEnd = ag($entity, 'IndexNumberEnd');
+            if (null !== $indexNumber && null !== $indexNumberEnd && $indexNumberEnd > $indexNumber) {
+                $episodeRangeLimit = (int)ag($context->options, Options::MAX_EPISODE_RANGE, 5);
+                $range = range(ag($entity, 'IndexNumber'), $indexNumberEnd);
+                if (count($range) > $episodeRangeLimit) {
                     $list[] = $this->process($context, $entity, $logContext, $opts);
+                } else {
+                    foreach (range((int)ag($entity, 'IndexNumber'), $indexNumberEnd) as $i) {
+                        $entity['IndexNumber'] = $i;
+                        $list[] = $this->process($context, $entity, $logContext, $opts);
+                    }
                 }
             } else {
-                $list[] = $this->process($context, $entity, $logContext, $opts);
+                $list[] = $this->process($context, $guid, $entity, $logContext, $opts);
             }
         }
 
@@ -217,14 +233,26 @@ class GetLibrary
      * Process the given item.
      *
      * @param Context $context The context object.
+     * @param iGuid $guid The guid object.
      * @param array $item The item to be processed.
      * @param array $log (optional) The log array.
      * @param array $opts (optional) The options array.
      *
-     * @return array<string,mixed> The processed metadata.
+     * @return array<string,mixed>|iState The processed metadata.
+     * @throws RuntimeException
+     * @throws InvalidArgumentException
      */
-    private function process(Context $context, array $item, array $log = [], array $opts = []): array
-    {
+    private function process(
+        Context $context,
+        iGuid $guid,
+        array $item,
+        array $log = [],
+        array $opts = []
+    ): array|iState {
+        if (true === (bool)ag($opts, Options::TO_ENTITY)) {
+            return $this->createEntity($context, $guid, $item, $opts);
+        }
+
         $url = $context->backendUrl->withPath(sprintf('/Users/%s/items/%s', $context->backendUser, ag($item, 'Id')));
         $possibleTitlesList = ['Name', 'OriginalTitle', 'SortName', 'ForcedSortName'];
 
@@ -246,14 +274,14 @@ class GetLibrary
         ]));
 
         $metadata = [
-            'id' => ag($item, 'Id'),
-            'type' => ucfirst(ag($item, 'Type', 'unknown')),
-            'library' => ag($log, 'library.title'),
+            iState::COLUMN_ID => ag($item, 'Id'),
+            iState::COLUMN_TYPE => ucfirst(ag($item, 'Type', 'unknown')),
+            iState::COLUMN_META_LIBRARY => ag($log, 'library.title'),
             'url' => (string)$url,
             'webUrl' => (string)$webUrl,
-            'title' => ag($item, $possibleTitlesList, '??'),
-            'year' => ag($item, 'ProductionYear'),
-            'guids' => [],
+            iState::COLUMN_TITLE => ag($item, $possibleTitlesList, '??'),
+            iState::COLUMN_YEAR => ag($item, 'ProductionYear'),
+            iState::COLUMN_GUIDS => [],
             'match' => [
                 'titles' => [],
                 'paths' => [],
@@ -293,12 +321,12 @@ class GetLibrary
 
         if (null !== ($providerIds = ag($item, 'ProviderIds'))) {
             foreach ($providerIds as $key => $val) {
-                $metadata['guids'][] = $key . '://' . $val;
+                $metadata[iState::COLUMN_GUIDS][] = $key . '://' . $val;
             }
         }
 
         if (true === (bool)ag($opts, Options::RAW_RESPONSE)) {
-            $metadata['raw'] = $item;
+            $metadata[Options::RAW_RESPONSE] = $item;
         }
 
         return $metadata;
diff --git a/src/Backends/Jellyfin/Action/Import.php b/src/Backends/Jellyfin/Action/Import.php
index ca15b486..1fa2d3f6 100644
--- a/src/Backends/Jellyfin/Action/Import.php
+++ b/src/Backends/Jellyfin/Action/Import.php
@@ -729,7 +729,6 @@ class Import
                             );
                             $callback(item: $entity, logContext: $logContext);
                         } else {
-                            $indexNumber = ag($entity, 'IndexNumber');
                             foreach ($range as $i) {
                                 $this->logger->debug(
                                     'Making virtual episode [{backend}] [{library.title}] [{segment.number}/{segment.of}] [{item.type}: {item.title}] [{item.indexNumber} => {item.i} of {item.indexNumberEnd}]',
diff --git a/src/Backends/Plex/Action/GetLibrary.php b/src/Backends/Plex/Action/GetLibrary.php
index 4c2a0699..14abe0e4 100644
--- a/src/Backends/Plex/Action/GetLibrary.php
+++ b/src/Backends/Plex/Action/GetLibrary.php
@@ -12,6 +12,7 @@ use App\Backends\Common\Levels;
 use App\Backends\Common\Response;
 use App\Backends\Plex\PlexActionTrait;
 use App\Backends\Plex\PlexClient;
+use App\Libs\Entity\StateInterface as iState;
 use App\Libs\Exceptions\Backends\RuntimeException;
 use App\Libs\Options;
 use JsonException;
@@ -59,6 +60,7 @@ final class GetLibrary
      * @throws ExceptionInterface
      * @throws InvalidArgumentException
      * @throws RuntimeException
+     * @throws \App\Libs\Exceptions\Backends\InvalidArgumentException
      */
     private function action(Context $context, iGuid $guid, string|int $id, array $opts = []): Response
     {
@@ -174,6 +176,10 @@ final class GetLibrary
                 continue;
             }
 
+            if (false === $this->isSupportedType(ag($entity, 'type'))) {
+                continue;
+            }
+
             $year = (int)ag($entity, 'year', 0);
 
             if (0 === $year && null !== ($airDate = ag($entity, 'originallyAvailableAt'))) {
@@ -215,20 +221,24 @@ final class GetLibrary
             );
         }
 
+        $noLog = (bool)ag($opts, Options::NO_LOGGING);
+
         foreach ($requests as $response) {
             $requestContext = ag($response->getInfo('user_data'), 'context', []);
 
             try {
                 if (200 !== $response->getStatusCode()) {
-                    $this->logger->warning(
-                        'Request for [{backend}] {item.type} [{item.title}] metadata returned with unexpected [{status_code}] status code.',
-                        [
-                            'backend' => $context->backendName,
-                            'status_code' => $response->getStatusCode(),
-                            ...$requestContext
-                        ]
-                    );
-
+                    if (false === $noLog) {
+                        $this->logger->warning(
+                            'Request for [{backend}] {item.type} [{item.title}] metadata returned with unexpected [{status_code}] status code.',
+                            [
+                                'backend' => $context->backendName,
+                                'status_code' => $response->getStatusCode(),
+                                'body' => $response->getContent(false),
+                                ...$requestContext
+                            ]
+                        );
+                    }
                     continue;
                 }
 
@@ -287,11 +297,21 @@ final class GetLibrary
      * @param array $log The log array. Default is an empty array.
      * @param array $opts The options array. Default is an empty array.
      *
-     * @return array Returns an array containing the processed metadata.
+     * @return array|iState Returns an array containing the processed metadata.
      * @throws RuntimeException Throws a RuntimeException if an unexpected item type is encountered while parsing the library.
+     * @throws \App\Libs\Exceptions\Backends\InvalidArgumentException Throws an InvalidArgumentException if the item type is not supported.
      */
-    private function process(Context $context, iGuid $guid, array $item, array $log = [], array $opts = []): array
-    {
+    private function process(
+        Context $context,
+        iGuid $guid,
+        array $item,
+        array $log = [],
+        array $opts = []
+    ): array|iState {
+        if (true === (bool)ag($opts, Options::TO_ENTITY)) {
+            return $this->createEntity($context, $guid, $item, $opts);
+        }
+
         $url = $context->backendUrl->withPath(r('/library/metadata/{item_id}', ['item_id' => ag($item, 'ratingKey')]));
         $possibleTitlesList = ['title', 'originalTitle', 'titleSort'];
 
@@ -319,14 +339,14 @@ final class GetLibrary
         );
 
         $metadata = [
-            'id' => (int)ag($item, 'ratingKey'),
-            'type' => ucfirst(ag($item, 'type', 'unknown')),
-            'library' => ag($log, 'library.title'),
+            iState::COLUMN_ID => (int)ag($item, 'ratingKey'),
+            iState::COLUMN_TYPE => ucfirst(ag($item, 'type', 'unknown')),
+            iState::COLUMN_META_LIBRARY => ag($log, 'library.title'),
             'url' => (string)$url,
             'webUrl' => (string)$webUrl,
-            'title' => ag($item, $possibleTitlesList, '??'),
-            'year' => $year,
-            'guids' => [],
+            iState::COLUMN_TITLE => ag($item, $possibleTitlesList, '??'),
+            iState::COLUMN_YEAR => $year,
+            iState::COLUMN_GUIDS => [],
             'match' => [
                 'titles' => [],
                 'paths' => [],
@@ -389,15 +409,15 @@ final class GetLibrary
         }
 
         if (null !== ($itemGuid = ag($item, 'guid')) && false === $guid->isLocal($itemGuid)) {
-            $metadata['guids'][] = $itemGuid;
+            $metadata[iState::COLUMN_GUIDS][] = $itemGuid;
         }
 
         foreach (array_column(ag($item, 'Guid', []), 'id') as $externalId) {
-            $metadata['guids'][] = $externalId;
+            $metadata[iState::COLUMN_GUIDS][] = $externalId;
         }
 
         if (true === (bool)ag($opts, Options::RAW_RESPONSE)) {
-            $metadata['raw'] = $item;
+            $metadata[Options::RAW_RESPONSE] = $item;
         }
 
         return $metadata;
diff --git a/src/Libs/Options.php b/src/Libs/Options.php
index 0d4f80ad..627a9e20 100644
--- a/src/Libs/Options.php
+++ b/src/Libs/Options.php
@@ -32,7 +32,7 @@ final class Options
     public const string MAX_EPISODE_RANGE = 'MAX_EPISODE_RANGE';
     public const string IGNORE = 'ignore';
     public const string PLEX_USE_OLD_PROGRESS_ENDPOINT = 'use_old_progress_endpoint';
-    public const string TO_ENTITY = 'to_entity';
+    public const string TO_ENTITY = 'TO_ENTITY';
 
     private function __construct()
     {