CONV-292: Add standard API error contract

app/Support/Api/ApiErrorResponseFactory.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Support\Api;
+
+use Illuminate\Http\JsonResponse;
+
+final class ApiErrorResponseFactory
+{
+    public function make(string $code, string $message, int $status = 400, array $details = []): JsonResponse
+    {
+        return response()->json([
+            'error' => [
+                'code' => $code,
+                'message' => $message,
+                'details' => $details,
+            ],
+        ], $status);
+    }
+}

tests/Unit/Support/Api/ApiErrorResponseFactoryTest.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Support\Api\ApiErrorResponseFactory;
+
+it('returns standard api error response shape', function () {
+    $factory = app(ApiErrorResponseFactory::class);
+
+    $response = $factory->make(
+        code: 'test_error',
+        message: 'Test error message.',
+        status: 422,
+        details: ['field' => 'value'],
+    );
+
+    expect($response->getStatusCode())->toBe(422);
+    expect($response->getData(true))->toBe([
+        'error' => [
+            'code' => 'test_error',
+            'message' => 'Test error message.',
+            'details' => ['field' => 'value'],
+        ],
+    ]);
+});
+
+it('defaults to empty details and 400 status', function () {
+    $factory = app(ApiErrorResponseFactory::class);
+
+    $response = $factory->make(code: 'some_error', message: 'Something went wrong.');
+
+    expect($response->getStatusCode())->toBe(400);
+    $data = $response->getData(true);
+    expect($data['error']['details'])->toBe([]);
+});