From 375ba1b4d5a0a5d2b5b6df37c1694abe6a3cda2b Mon Sep 17 00:00:00 2001
From: Ron Rise <ron@siteworxpro.com>
Date: Mon, 1 Dec 2025 11:05:29 -0500
Subject: [PATCH] feat: implement GenericResponse class and update controllers
 to use it for consistent JSON responses

---
 src/Controllers/HealthcheckController.php |  3 ++-
 src/Controllers/IndexController.php       | 17 ++++--------
 src/Controllers/OpenApiController.php     |  1 +
 src/Http/JsonResponseFactory.php          | 13 ++++++---
 src/Http/Responses/GenericResponse.php    | 32 +++++++++++++++++++++++
 5 files changed, 50 insertions(+), 16 deletions(-)
 create mode 100644 src/Http/Responses/GenericResponse.php

diff --git a/src/Controllers/HealthcheckController.php b/src/Controllers/HealthcheckController.php
index f1884fa..ac93f20 100644
--- a/src/Controllers/HealthcheckController.php
+++ b/src/Controllers/HealthcheckController.php
@@ -8,6 +8,7 @@ use Illuminate\Database\PostgresConnection;
 use Nyholm\Psr7\ServerRequest;
 use Psr\Http\Message\ResponseInterface;
 use Siteworxpro\App\Http\JsonResponseFactory;
+use Siteworxpro\App\Http\Responses\GenericResponse;
 use Siteworxpro\App\Models\Model;
 use Siteworxpro\App\Services\Facades\Redis;
 use Siteworxpro\HttpStatus\CodesEnum;
@@ -53,7 +54,7 @@ class HealthcheckController extends Controller
         }
 
         return JsonResponseFactory::createJsonResponse(
-            ['status_code' => 200, 'message' => 'Healthcheck OK']
+            new GenericResponse('Healthcheck OK', CodesEnum::OK->value)
         );
     }
 }
diff --git a/src/Controllers/IndexController.php b/src/Controllers/IndexController.php
index c5d1c70..5ccb26e 100644
--- a/src/Controllers/IndexController.php
+++ b/src/Controllers/IndexController.php
@@ -11,6 +11,7 @@ use Siteworxpro\App\Docs\TokenSecurity;
 use Siteworxpro\App\Docs\UnauthorizedResponse;
 use Siteworxpro\App\Http\JsonResponseFactory;
 use OpenApi\Attributes as OA;
+use Siteworxpro\App\Http\Responses\GenericResponse;
 
 /**
  * Class IndexController
@@ -31,15 +32,12 @@ class IndexController extends Controller
     #[OA\Response(
         response: '200',
         description: 'An Example Response',
-        content: new OA\JsonContent(properties: [
-            new OA\Property('status_code', type: 'integer'),
-            new OA\Property('message', type: 'string'),
-        ])
+        content: new OA\JsonContent(ref: '#/components/schemas/GenericResponse')
     )]
     #[UnauthorizedResponse]
     public function get(ServerRequest $request): ResponseInterface
     {
-        return JsonResponseFactory::createJsonResponse(['status_code' => 200, 'message' => 'Server is running']);
+        return JsonResponseFactory::createJsonResponse(['message' => 'Server is running']);
     }
 
     /**
@@ -53,16 +51,11 @@ class IndexController extends Controller
     #[OA\Response(
         response: '200',
         description: 'An Example Response',
-        content: new OA\JsonContent(
-            properties: [
-                new OA\Property('status_code', type: 'integer'),
-                new OA\Property('message', type: 'string'),
-            ]
-        )
+        content: new OA\JsonContent(ref: '#/components/schemas/GenericResponse')
     )]
     #[UnauthorizedResponse]
     public function post(ServerRequest $request): ResponseInterface
     {
-        return JsonResponseFactory::createJsonResponse(['status_code' => 200, 'message' => 'Server is running']);
+        return JsonResponseFactory::createJsonResponse(new GenericResponse('POST request received'));
     }
 }
diff --git a/src/Controllers/OpenApiController.php b/src/Controllers/OpenApiController.php
index 0fdeda9..85b5513 100644
--- a/src/Controllers/OpenApiController.php
+++ b/src/Controllers/OpenApiController.php
@@ -22,6 +22,7 @@ class OpenApiController extends Controller
         $openapi = new Generator()->generate([
             __DIR__ . '/../Controllers',
             __DIR__ . '/../Models',
+            __DIR__ . '/../Http/Responses',
         ]);
 
         $response = new Response();
diff --git a/src/Http/JsonResponseFactory.php b/src/Http/JsonResponseFactory.php
index 005412f..69eb779 100644
--- a/src/Http/JsonResponseFactory.php
+++ b/src/Http/JsonResponseFactory.php
@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Siteworxpro\App\Http;
 
+use Illuminate\Contracts\Support\Arrayable;
 use Nyholm\Psr7\Response;
 use Siteworxpro\HttpStatus\CodesEnum;
 
@@ -17,13 +18,19 @@ class JsonResponseFactory
     /**
      * Create a JSON response with the given data and status code.
      *
-     * @param array $data The data to include in the response.
+     * @param array|Arrayable $data The data to include in the response.
      * @param CodesEnum $statusCode The HTTP status code for the response.
      * @return Response The JSON response.
      * @throws \JsonException
      */
-    public static function createJsonResponse(array $data, CodesEnum $statusCode = CodesEnum::OK): Response
-    {
+    public static function createJsonResponse(
+        array|Arrayable $data,
+        CodesEnum $statusCode = CodesEnum::OK
+    ): Response {
+        if ($data instanceof Arrayable) {
+            $data = $data->toArray();
+        }
+
         return new Response(
             status: $statusCode->value,
             headers: [
diff --git a/src/Http/Responses/GenericResponse.php b/src/Http/Responses/GenericResponse.php
new file mode 100644
index 0000000..93d01e6
--- /dev/null
+++ b/src/Http/Responses/GenericResponse.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Siteworxpro\App\Http\Responses;
+
+use Illuminate\Contracts\Support\Arrayable;
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    schema: 'GenericResponse',
+    properties: [
+        new OA\Property(property: 'message', type: 'string', example: 'Operation completed successfully.'),
+        new OA\Property(property: 'status_code', type: 'integer', example: 200),
+    ]
+)]
+readonly class GenericResponse implements Arrayable
+{
+    public function __construct(
+        private string $message = '',
+        private int $statusCode = 200
+    ) {
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'message' => $this->message,
+            'status_code' => $this->statusCode,
+        ];
+    }
+}