[pull] main from AzuraCast:main

backend/src/Controller/Api/Admin/StorageLocationsController.php

@@ -165,9 +165,7 @@ protected function viewRecord(object $record, ServerRequest $request): object
     {
         $original = parent::viewRecord($record, $request);
 
-        $return = new ApiStorageLocation();
-        $return->fromParentObject($original);
-
+        $return = ApiStorageLocation::fromParent($original);
         $return->storageQuotaBytes = (string)($record->getStorageQuotaBytes() ?? '');
         $return->storageUsedBytes = (string)$record->getStorageUsedBytes();
         $return->storageUsedPercent = $record->getStorageUsePercentage();

backend/src/Controller/Api/Admin/Updates/GetUpdatesAction.php

@@ -6,16 +6,33 @@
 
 use App\Container\SettingsAwareTrait;
 use App\Controller\SingleActionInterface;
+use App\Entity\Api\Admin\UpdateDetails;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
 use App\Service\AzuraCastCentral;
 use GuzzleHttp\Exception\TransferException;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 use RuntimeException;
 
-/*
- * TODO API
- */
+#[OA\Get(
+    path: '/admin/updates',
+    operationId: 'getUpdateStatus',
+    description: 'Show information about this installation and its update status.',
+    tags: ['Administration: General'],
+    responses: [
+        new OA\Response(
+            response: 200,
+            description: 'Success',
+            content: new OA\JsonContent(
+                ref: UpdateDetails::class
+            )
+        ),
+        new OA\Response(ref: OpenApi::REF_RESPONSE_ACCESS_DENIED, response: 403),
+        new OA\Response(ref: OpenApi::REF_RESPONSE_GENERIC_ERROR, response: 500),
+    ]
+)]
 final class GetUpdatesAction implements SingleActionInterface
 {
     use SettingsAwareTrait;
@@ -40,7 +57,7 @@ public function __invoke(
                 $settings->updateUpdateLastRun();
                 $this->writeSettings($settings);
 
-                return $response->withJson($updates);
+                return $response->withJson(UpdateDetails::fromParent($updates));
             }
 
             throw new RuntimeException('Error parsing update data response from AzuraCast central.');

backend/src/Controller/Api/Admin/Updates/PutUpdatesAction.php

@@ -8,12 +8,22 @@
 use App\Entity\Api\Status;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
 use App\Service\WebUpdater;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[OA\Put(
+    path: '/admin/updates',
+    operationId: 'putWebUpdate',
+    description: 'Attempts to trigger a web-based update.',
+    tags: ['Administration: General'],
+    responses: [
+        new OA\Response(ref: OpenApi::REF_RESPONSE_SUCCESS, response: 200),
+        new OA\Response(ref: OpenApi::REF_RESPONSE_ACCESS_DENIED, response: 403),
+        new OA\Response(ref: OpenApi::REF_RESPONSE_GENERIC_ERROR, response: 500),
+    ]
+)]
 final class PutUpdatesAction implements SingleActionInterface
 {
     public function __construct(

backend/src/Controller/Api/Frontend/Dashboard/NotificationsAction.php

@@ -6,14 +6,34 @@
 
 use App\CallableEventDispatcherInterface;
 use App\Controller\SingleActionInterface;
+use App\Entity\Api\Notification;
 use App\Event;
 use App\Http\Response;
 use App\Http\ServerRequest;
+use App\OpenApi;
+use OpenApi\Attributes as OA;
 use Psr\Http\Message\ResponseInterface;
 
-/*
- * TODO API
- */
+#[OA\Get(
+    path: '/dashboard/notifications',
+    operationId: 'getNotifications',
+    description: 'Show all notifications your current account should see.',
+    tags: ['Miscellaneous'],
+    responses: [
+        new OA\Response(
+            response: 200,
+            description: 'Success',
+            content: new OA\JsonContent(
+                type: 'array',
+                items: new OA\Items(
+                    ref: Notification::class
+                )
+            )
+        ),
+        new OA\Response(ref: OpenApi::REF_RESPONSE_ACCESS_DENIED, response: 403),
+        new OA\Response(ref: OpenApi::REF_RESPONSE_GENERIC_ERROR, response: 500),
+    ]
+)]
 final class NotificationsAction implements SingleActionInterface
 {
     public function __construct(

backend/src/Controller/Api/Frontend/Dashboard/StationsAction.php

@@ -83,9 +83,7 @@ static function (Station $station) use ($acl) {
 
         $paginator->setPostprocessor(
             function (NowPlaying $np) use ($router, $listenersEnabled, $acl) {
-                $row = new Dashboard();
-                $row->fromParentObject($np);
-
+                $row = Dashboard::fromParent($np);
                 $row->links = [
                     'public' => $router->named('public:index', ['station_id' => $np->station->shortcode]),
                     'manage' => $router->named('stations:index:index', ['station_id' => $np->station->id]),

backend/src/Controller/Api/Stations/QueueController.php

@@ -141,9 +141,7 @@ protected function viewRecord(object $record, ServerRequest $request): StationQu
 
         $row = $this->queueApiGenerator->__invoke($record);
 
-        $apiResponse = new StationQueueDetailed();
-        $apiResponse->fromParentObject($row);
-
+        $apiResponse = StationQueueDetailed::fromParent($row);
         $apiResponse->sent_to_autodj = $record->getSentToAutodj();
         $apiResponse->is_played = $record->getIsPlayed();
         $apiResponse->autodj_custom_uri = $record->getAutodjCustomUri();

backend/src/Controller/Api/Stations/RemotesController.php

@@ -181,8 +181,7 @@ protected function viewRecord(object $record, ServerRequest $request): ApiStatio
     {
         $returnArray = $this->toArray($record);
 
-        $return = new ApiStationRemote();
-        $return->fromParentObject($returnArray);
+        $return = ApiStationRemote::fromParent($returnArray);
 
         $isInternal = $request->isInternal();
         $router = $request->getRouter();

backend/src/Entity/Api/Admin/UpdateDetails.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Entity\Api\Admin;
+
+use App\Traits\LoadFromParentObject;
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'Api_Admin_UpdateDetails',
+    type: 'object'
+)]
+final readonly class UpdateDetails
+{
+    use LoadFromParentObject;
+
+    public function __construct(
+        #[OA\Property(
+            description: 'The stable-equivalent branch your installation currently appears to be on.',
+            example: '0.20.3'
+        )]
+        public string $current_release,
+        #[OA\Property(
+            description: 'The current latest stable release of the software.',
+            example: '0.20.4'
+        )]
+        public string $latest_release,
+        #[OA\Property(
+            description: 'If you are on the Rolling Release, whether your installation needs to be updated.',
+        )]
+        public bool $needs_rolling_update = false,
+        #[OA\Property(
+            description: 'Whether a newer stable release is available than the version you are currently using.',
+        )]
+        public bool $needs_release_update = false,
+        #[OA\Property(
+            description: 'If you are on the Rolling Release, the number of updates released since your version.',
+        )]
+        public int $rolling_updates_available = 0,
+        #[OA\Property(
+            description: 'Whether you can seamlessly move from the Rolling Release channel to Stable without issues.',
+        )]
+        public bool $can_switch_to_stable = false
+    ) {
+    }
+}

backend/src/Entity/Api/Notification.php

@@ -4,15 +4,27 @@
 
 namespace App\Entity\Api;
 
-final class Notification
-{
-    public string $title;
-
-    public string $body;
-
-    public string $type;
+use App\Enums\FlashLevels;
+use OpenApi\Attributes as OA;
 
-    public ?string $actionLabel;
-
-    public ?string $actionUrl;
+#[OA\Schema(
+    schema: 'Api_Notification',
+    required: ['*'],
+    type: 'object'
+)]
+final readonly class Notification
+{
+    public function __construct(
+        #[OA\Property]
+        public string $title,
+        #[OA\Property]
+        public string $body,
+        #[OA\Property]
+        public FlashLevels $type,
+        #[OA\Property]
+        public ?string $actionLabel = null,
+        #[OA\Property]
+        public ?string $actionUrl = null
+    ) {
+    }
 }

backend/src/Entity/ApiGenerator/NowPlayingApiGenerator.php

@@ -107,8 +107,7 @@ public function __invoke(
             isNowPlaying: true
         );
 
-        $apiCurrentSong = new CurrentSong();
-        $apiCurrentSong->fromParentObject($apiSongHistory);
+        $apiCurrentSong = CurrentSong::fromParent($apiSongHistory);
         $np->now_playing = $apiCurrentSong;
 
         $np->song_history = $this->songHistoryApiGenerator->fromArray(

backend/src/Entity/ApiGenerator/SongHistoryApiGenerator.php

@@ -91,8 +91,7 @@ public function detailed(
         ?UriInterface $baseUri = null
     ): DetailedSongHistory {
         $apiHistory = ($this)($record, $baseUri);
-        $response = new DetailedSongHistory();
-        $response->fromParentObject($apiHistory);
+        $response = DetailedSongHistory::fromParent($apiHistory);
         $response->listeners_start = (int)$record->getListenersStart();
         $response->listeners_end = (int)$record->getListenersEnd();
         $response->delta_total = $record->getDeltaTotal();

backend/src/Session/FlashLevels.php → backend/src/Enums/FlashLevels.php

@@ -2,8 +2,11 @@
 
 declare(strict_types=1);
 
-namespace App\Session;
+namespace App\Enums;
 
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(type: 'string')]
 enum FlashLevels: string
 {
     case Success = 'success';

backend/src/Event/GetNotifications.php

@@ -10,6 +10,7 @@
 
 final class GetNotifications extends Event
 {
+    /** @var Notification[] */
     private array $notifications = [];
 
     public function __construct(

backend/src/Notification/Check/BaseUrlCheck.php

@@ -6,9 +6,9 @@
 
 use App\Container\SettingsAwareTrait;
 use App\Entity\Api\Notification;
+use App\Enums\FlashLevels;
 use App\Enums\GlobalPermissions;
 use App\Event\GetNotifications;
-use App\Session\FlashLevels;
 
 final class BaseUrlCheck
 {
@@ -47,18 +47,19 @@ public function __invoke(GetNotifications $event): void
             );
             // phpcs:enable Generic.Files.LineLength
 
-            $notification = new Notification();
-            $notification->title = sprintf(
-                __('Your "Base URL" setting (%s) does not match the URL you are currently using (%s).'),
-                (string)$baseUriWithoutRequest,
-                (string)$baseUriWithRequest
+            $event->addNotification(
+                new Notification(
+                    sprintf(
+                        __('Your "Base URL" setting (%s) does not match the URL you are currently using (%s).'),
+                        (string)$baseUriWithoutRequest,
+                        (string)$baseUriWithRequest
+                    ),
+                    implode(' ', $notificationBodyParts),
+                    FlashLevels::Warning,
+                    __('System Settings'),
+                    $router->named('admin:settings:index')
+                )
             );
-            $notification->body = implode(' ', $notificationBodyParts);
-            $notification->type = FlashLevels::Warning->value;
-            $notification->actionLabel = __('System Settings');
-            $notification->actionUrl = $router->named('admin:settings:index');
-
-            $event->addNotification($notification);
         }
     }
 }

backend/src/Notification/Check/DonateAdvisorCheck.php

@@ -6,9 +6,9 @@
 
 use App\Container\EnvironmentAwareTrait;
 use App\Entity\Api\Notification;
+use App\Enums\FlashLevels;
 use App\Event\GetNotifications;
 use App\Exception\Http\RateLimitExceededException;
-use App\Session\FlashLevels;
 
 final class DonateAdvisorCheck
 {
@@ -29,17 +29,17 @@ public function __invoke(GetNotifications $event): void
             return;
         }
 
-        $notification = new Notification();
-        $notification->title = __('AzuraCast is free and open-source software.');
-        $notification->body = __(
-            'If you are enjoying AzuraCast, please consider donating to support our work. We depend ' .
-            'on donations to build new features, fix bugs, and keep AzuraCast modern, accessible and free.',
+        $event->addNotification(
+            new Notification(
+                __('AzuraCast is free and open-source software.'),
+                __(
+                    'If you are enjoying AzuraCast, please consider donating to support our work. We depend ' .
+                    'on donations to build new features, fix bugs, and keep AzuraCast modern, accessible and free.',
+                ),
+                FlashLevels::Info,
+                __('Donate to AzuraCast'),
+                'https://donate.azuracast.com/'
+            )
         );
-        $notification->type = FlashLevels::Info->value;
-
-        $notification->actionLabel = __('Donate to AzuraCast');
-        $notification->actionUrl = 'https://donate.azuracast.com/';
-
-        $event->addNotification($notification);
     }
 }