I respones

src/Middleware/RequireAuthMiddleware.php

@@ -2,7 +2,7 @@
 
 namespace Blax\Workkit\Middleware;
 
-use Blax\Workkit\Services\MiscService;
+use Blax\Workkit\Services\ResponseService;
 use Closure;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Auth;
@@ -18,9 +18,10 @@ class RequireAuthMiddleware
     public function handle(Request $request, Closure $next, string $action = 'continue'): Response
     {
         if (! Auth::check()) {
-            return response()->json(
+            return ResponseService::apiError(
-                MiscService::apiResponse(['message' => "You need to be logged in to {$action}."]),
+                "You need to be logged in to {$action}.",
                 Response::HTTP_UNAUTHORIZED,
+                type: 'AuthenticationException',
             );
         }
 

src/Services/MiscService.php

@@ -8,12 +8,13 @@ use Illuminate\Support\Facades\Log;
 /**
  * Grab-bag of small utilities used across Blax host apps.
  *
- * Response-envelope helpers (`response`, `apiResponse`, `apiMeta`,
+ * Response-envelope helpers live on {@see ResponseService} now and the old
- * `apiItem`, `apiCollection`, `apiPaginated`, `asPaginated`,
+ * shims here have been retired alongside the legacy methods
- * `paginationMeta`, `availableLanguages`) have moved to
+ * (`response`, `apiResponse`, `asPaginated`, `paginationMeta`) that were
- * {@see ResponseService} — they remain here as thin shims so existing
+ * dropped from ResponseService itself. The remaining `apiItem`,
- * callers continue to work without changes. Prefer calling
+ * `apiCollection`, `apiPaginated`, `apiMeta`, `availableLanguages` shims
- * {@see ResponseService} directly in new code.
+ * stay for the moment as a courtesy to existing callers — new code should
+ * call {@see ResponseService} directly.
  */
 class MiscService
 {
@@ -21,14 +22,6 @@ class MiscService
      * Response envelope (delegates to ResponseService)
      * ────────────────────────────────────────────────────────────────────── */
 
-    /**
-     * Build a raw `{ data, meta }` envelope. See {@see ResponseService::response()}.
-     */
-    public static function response(mixed $data = null, array $meta = []): array
-    {
-        return ResponseService::response($data, $meta);
-    }
-
     /**
      * Available content languages for the running app.
      * See {@see ResponseService::availableLanguages()}.
@@ -59,15 +52,6 @@ class MiscService
         return ResponseService::apiItem($item, $resource_class, $extraMeta);
     }
 
-    /**
-     * Plain envelope with the standard meta block.
-     * See {@see ResponseService::apiResponse()}.
-     */
-    public static function apiResponse(mixed $data = null, array $extraMeta = []): array
-    {
-        return ResponseService::apiResponse($data, $extraMeta);
-    }
-
     /**
      * Non-paginated collection envelope.
      * See {@see ResponseService::apiCollection()}.
@@ -89,30 +73,6 @@ class MiscService
         return ResponseService::apiPaginated($paginated, $resource_class, $extraMeta);
     }
 
-    /**
-     * Legacy paginated meta block.
-     * See {@see ResponseService::paginationMeta()}.
-     */
-    public static function paginationMeta(mixed $paginated, array $options = [], array $meta = []): array
-    {
-        return ResponseService::paginationMeta($paginated, $options, $meta);
-    }
-
-    /**
-     * Legacy paginated envelope.
-     * See {@see ResponseService::asPaginated()}.
-     *
-     * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>  $resource_class
-     */
-    public static function asPaginated(
-        mixed $paginated,
-        string $resource_class,
-        array $meta = [],
-        ?array $options = null,
-    ): array {
-        return ResponseService::asPaginated($paginated, $resource_class, $meta, $options);
-    }
-
     /* ──────────────────────────────────────────────────────────────────────
      * Misc utilities
      * ────────────────────────────────────────────────────────────────────── */

src/Services/ResponseService.php

@@ -2,45 +2,47 @@
 
 namespace Blax\Workkit\Services;
 
-use Illuminate\Contracts\Pagination\Paginator;
+use Illuminate\Http\JsonResponse;
+use Symfony\Component\HttpFoundation\Response;
+use Throwable;
 
 /**
  * API response envelope builder.
  *
- * Every method here produces the workkit response shape `{ data, meta }`.
+ * Every helper here — success or error — produces the same wire shape:
- * The richer helpers (`apiItem`, `apiCollection`, `apiPaginated`,
- * `apiResponse`) auto-fill a standard meta block via {@see apiMeta()},
- * which carries the request `url`, the active `locale`, and the list of
- * available `languages`. Pagination metadata is merged on top by
- * {@see apiPaginated()}.
  *
- * This service is the canonical home for these helpers. The matching
+ *   {
- * methods on {@see MiscService} remain as thin shims for backward
+ *     "status":  { "code": <int>, "text": <reason phrase> },
- * compatibility — existing callers do not need to change.
+ *     "message": <human readable | null>,
+ *     "data":    <payload | absent>,        // success only
+ *     "error":   <{ type, ... } | absent>,  // error only
+ *     "errors":  <{ field: [...] } | absent>, // present for validation errors
+ *     "meta":    { url, locale, languages, ...pagination... }
+ *   }
  *
- * Lifecycle in a controller:
+ * The split is: `data` carries success payloads, `error` carries failure
+ * details, `errors` is the Laravel-compatible field-map alias so
+ * `assertJsonValidationErrors([...])` keeps working without re-jiggering tests.
+ * Every response also reports its HTTP status as both code and reason phrase
+ * inside the body — useful for clients that can't easily inspect headers.
  *
- *   return response()->json(ResponseService::apiPaginated($q->paginate(), BookResource::class));
+ * Controller lifecycle under {@see \Blax\Workkit\Middleware\ForceJsonResponse}:
- *   return response()->json(ResponseService::apiItem($book, BookResource::class));
+ *
- *   return response()->json(ResponseService::apiResponse(['token' => $token]), 201);
+ *   200 OK         → return ResponseService::apiItem(...) (plain array)
+ *   200 OK list    → return ResponseService::apiPaginated($q->paginate(...), ...)
+ *   201 Created    → return ResponseService::apiCreated(...) (JsonResponse)
+ *   202 Accepted   → return ResponseService::apiAccepted(...) (JsonResponse)
+ *   204 No Content → return ResponseService::apiNoContent()  (JsonResponse)
+ *   4xx/5xx        → return ResponseService::apiError(...)   (JsonResponse)
+ *   422 validation → return ResponseService::apiValidationError([...]) (JsonResponse)
+ *
+ * Reach for `response()->json(...)` directly only if you genuinely need a
+ * status code or shape not modeled above — in which case prefer to add a
+ * helper here so the convention stays uniform.
  */
 class ResponseService
 {
-    /**
+    /* ─────────────────────────── building blocks ──────────────────────── */
-     * Build a raw `{ data, meta }` envelope with whatever meta you pass.
-     *
-     * Lowest-level primitive — every other method here ultimately produces
-     * this same shape. Prefer the higher-level helpers
-     * (`apiResponse`, `apiItem`, `apiCollection`, `apiPaginated`) which
-     * auto-fill the standard meta block.
-     */
-    public static function response(mixed $data = null, array $meta = []): array
-    {
-        return [
-            'data' => $data,
-            'meta' => $meta,
-        ];
-    }
 
     /**
      * Available content languages for the running app.
@@ -73,10 +75,8 @@ class ResponseService
     }
 
     /**
-     * Standard meta block: `url`, `locale`, `languages`, plus any extras.
+     * Standard meta block: `url`, `locale`, `languages`, plus any extras
-     *
+     * (the per-helper additions like pagination keys land here).
-     * Pagination keys are merged in by {@see apiPaginated()};
-     * {@see apiItem()} and {@see apiCollection()} skip them.
      *
      * @param  array<string, mixed>  $extra
      * @return array<string, mixed>
@@ -91,92 +91,98 @@ class ResponseService
     }
 
     /**
-     * Single-item envelope. Use for any `show`-style endpoint.
+     * Internal envelope builder used by every success/error helper. Keeping
+     * a single source of truth here means the wire shape can't drift between
+     * helpers — a new top-level key only needs to be added in one place.
      *
-     * Pass the resource class to wrap the model in a `JsonResource`, or
+     * @param  array<string, mixed>  $payload Body keys (data/error/errors)
-     * omit it to serialize the value directly (this is also the form to
+     * @param  array<string, mixed>  $extraMeta
-     * use for arbitrary payloads — login responses, action acks, etc.).
+     * @return array<string, mixed>
+     */
+    private static function envelope(
+        int $statusCode,
+        ?string $message,
+        array $payload,
+        array $extraMeta = [],
+    ): array {
+        return array_merge([
+            'status' => [
+                'code' => $statusCode,
+                'text' => Response::$statusTexts[$statusCode] ?? 'Unknown',
+            ],
+            'message' => $message,
+        ], $payload, [
+            'meta' => self::apiMeta($extraMeta),
+        ]);
+    }
+
+    /* ─────────────────────────────── success ──────────────────────────── */
+
+    /**
+     * Single-item envelope. Use for any `show`-style endpoint or for an
+     * arbitrary payload (login receipt, ack, etc. — pass `null` resource).
      *
      * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>|null  $resourceClass
      * @param  array<string, mixed>  $extraMeta
-     * @return array{data: mixed, meta: array<string, mixed>}
+     * @return array{status: array{code:int,text:string}, message: ?string, data: mixed, meta: array<string, mixed>}
      */
-    public static function apiItem(mixed $item, ?string $resourceClass = null, array $extraMeta = []): array
+    public static function apiItem(
-    {
+        mixed $item,
-        return self::response(
+        ?string $resourceClass = null,
-            $resourceClass !== null ? $resourceClass::make($item) : $item,
+        array $extraMeta = [],
-            self::apiMeta($extraMeta),
+        ?string $message = null,
-        );
+    ): array {
+        return self::envelope(200, $message, [
+            'data' => $resourceClass !== null ? $resourceClass::make($item) : $item,
+        ], $extraMeta);
     }
 
     /**
-     * Plain envelope with the standard meta block.
+     * Non-paginated collection envelope. Reserve for genuinely tiny fixed
-     *
+     * lists (an enum, a child collection embedded in a parent response).
-     * Alias of `apiItem($data, null, $extraMeta)` kept for callers whose
+     * Most list endpoints should use {@see apiPaginated()}.
-     * intent is "arbitrary payload" rather than "model" — login responses,
-     * acknowledgements, etc.
-     *
-     * @param  array<string, mixed>  $extraMeta
-     * @return array{data: mixed, meta: array<string, mixed>}
-     */
-    public static function apiResponse(mixed $data = null, array $extraMeta = []): array
-    {
-        return self::apiItem($data, null, $extraMeta);
-    }
-
-    /**
-     * Non-paginated collection envelope.
-     *
-     * Reserve this for genuinely tiny fixed lists (an enum, a child
-     * collection embedded in a parent show response). Most list endpoints
-     * should use {@see apiPaginated()}.
      *
      * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>  $resourceClass
      * @param  array<string, mixed>  $extraMeta
-     * @return array{data: mixed, meta: array<string, mixed>}
+     * @return array<string, mixed>
      */
-    public static function apiCollection(iterable $items, string $resourceClass, array $extraMeta = []): array
+    public static function apiCollection(
-    {
+        iterable $items,
+        string $resourceClass,
+        array $extraMeta = [],
+        ?string $message = null,
+    ): array {
         $count = is_countable($items) ? count($items) : null;
 
-        return self::response(
+        return self::envelope(200, $message, [
-            $resourceClass::collection($items),
+            'data' => $resourceClass::collection($items),
-            self::apiMeta(array_merge(['total' => $count], $extraMeta)),
+        ], array_merge(['total' => $count], $extraMeta));
-        );
     }
 
     /**
-     * Paginated envelope. Use for any `index`-style endpoint.
+     * Paginated envelope. Use for any `index`-style endpoint. The meta block
-     *
+     * picks up the paginator's `current_page`, `per_page`, `from`, `to`,
-     * Wire shape:
+     * `total`, `total_pages` / `last_page` (aliased so legacy clients keep
-     *
+     * working) and a `has_more` boolean.
-     *   {
-     *     "data": [...resource collection...],
-     *     "meta": {
-     *       "url", "locale", "languages",
-     *       "current_page", "per_page", "from", "to",
-     *       "total", "total_pages", "last_page", "has_more"
-     *     }
-     *   }
-     *
-     * `last_page` is exposed alongside `total_pages` as an alias so
-     * consumers written against Laravel's native paginator key continue
-     * to work without a migration.
      *
      * @param  \Illuminate\Contracts\Pagination\Paginator|mixed  $paginated
      * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>  $resourceClass
      * @param  array<string, mixed>  $extraMeta
-     * @return array{data: mixed, meta: array<string, mixed>}
+     * @return array<string, mixed>
      */
-    public static function apiPaginated(mixed $paginated, string $resourceClass, array $extraMeta = []): array
+    public static function apiPaginated(
-    {
+        mixed $paginated,
+        string $resourceClass,
+        array $extraMeta = [],
+        ?string $message = null,
+    ): array {
         $arr = method_exists($paginated, 'toArray') ? $paginated->toArray() : [];
         $current = $arr['current_page'] ?? 1;
         $last = $arr['last_page'] ?? null;
 
-        return self::response(
+        return self::envelope(200, $message, [
-            $resourceClass::collection($paginated),
+            'data' => $resourceClass::collection($paginated),
-            self::apiMeta(array_merge([
+        ], array_merge([
             'current_page' => $current,
             'per_page' => $arr['per_page'] ?? null,
             'from' => $arr['from'] ?? null,
@@ -185,70 +191,130 @@ class ResponseService
             'total_pages' => $last,
             'last_page' => $last,
             'has_more' => $last !== null && $current < $last,
-            ], $extraMeta)),
+        ], $extraMeta));
+    }
+
+    /**
+     * Single-item envelope wrapped in a 201 Created JsonResponse. Use for
+     * any `store`-style endpoint.
+     *
+     * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>|null  $resourceClass
+     * @param  array<string, mixed>  $extraMeta
+     */
+    public static function apiCreated(
+        mixed $item,
+        ?string $resourceClass = null,
+        array $extraMeta = [],
+        ?string $message = null,
+    ): JsonResponse {
+        return response()->json(
+            self::envelope(201, $message, [
+                'data' => $resourceClass !== null ? $resourceClass::make($item) : $item,
+            ], $extraMeta),
+            Response::HTTP_CREATED,
         );
     }
 
     /**
-     * Legacy paginated meta block: slimmer than {@see apiMeta()}, no
+     * 202 Accepted envelope — for endpoints that queue work and return a
-     * `url`/`locale`/`languages`, includes a passthrough `options` object
+     * receipt rather than the final resource.
-     * reflecting the request's filter/sort state.
      *
-     * Retained for backward compatibility — new code should use
+     * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>|null  $resourceClass
-     * {@see apiPaginated()}.
+     * @param  array<string, mixed>  $extraMeta
-     *
-     * @param  \Illuminate\Contracts\Pagination\Paginator|mixed  $paginated
-     * @param  array<string, mixed>  $options
-     * @param  array<string, mixed>  $meta
-     * @return array<string, mixed>
      */
-    public static function paginationMeta(mixed $paginated, array $options = [], array $meta = []): array
+    public static function apiAccepted(
+        mixed $item = null,
+        ?string $resourceClass = null,
+        array $extraMeta = [],
+        ?string $message = null,
+    ): JsonResponse {
+        return response()->json(
+            self::envelope(202, $message, [
+                'data' => $resourceClass !== null ? $resourceClass::make($item) : $item,
+            ], $extraMeta),
+            Response::HTTP_ACCEPTED,
+        );
+    }
+
+    /**
+     * 204 No Content — carries no body. Useful for `delete`-style endpoints.
+     */
+    public static function apiNoContent(): JsonResponse
     {
-        $data = method_exists($paginated, 'toArray') ? $paginated->toArray() : [];
+        return response()->json(null, Response::HTTP_NO_CONTENT);
+    }
 
-        $base = [
+    /* ──────────────────────────────── errors ──────────────────────────── */
-            'from' => $data['from'] ?? null,
-            'to' => $data['to'] ?? null,
-            'total' => $data['total'] ?? null,
-            'last_page' => $data['last_page'] ?? null,
-            'current_page' => $data['current_page'] ?? null,
-            'options' => (object) $options,
-        ];
 
-        return $meta ? array_merge($base, $meta) : $base;
+    /**
+     * Generic error envelope. Accepts either:
+     *
+     *   - A {@see \Throwable} instance — its class becomes `error.type` and
+     *     its message becomes the envelope `message` (both overridable).
+     *   - A plain string — used as the envelope `message`. `type` defaults
+     *     to `'Error'` unless you pass it explicitly.
+     *
+     *     return ResponseService::apiError($e, 422, ['book' => ['...']]);
+     *     return ResponseService::apiError('Forbidden', 403);
+     *     return ResponseService::apiError('Rate limited', 429, type: 'TooManyRequests');
+     *
+     * @param  array<string, array<int, string>>  $errors Field-keyed
+     *         validation-style errors, mirrored into the top-level `errors`
+     *         key for {@see \Illuminate\Testing\TestResponse::assertJsonValidationErrors()}.
+     * @param  array<string, mixed>  $extraMeta
+     */
+    public static function apiError(
+        Throwable|string $errorOrMessage,
+        int $status = 500,
+        array $errors = [],
+        ?string $type = null,
+        ?string $message = null,
+        array $extraMeta = [],
+    ): JsonResponse {
+        if ($errorOrMessage instanceof Throwable) {
+            $type ??= class_basename($errorOrMessage);
+            $message ??= $errorOrMessage->getMessage();
+        } else {
+            $message ??= $errorOrMessage;
+            $type ??= 'Error';
+        }
+
+        $payload = ['error' => ['type' => $type]];
+        if (! empty($errors)) {
+            $payload['errors'] = $errors;
+        }
+
+        return response()->json(
+            self::envelope($status, $message, $payload, $extraMeta),
+            $status,
+        );
     }
 
     /**
-     * Legacy paginated envelope. Same intent as {@see apiPaginated()} but
+     * 422 Unprocessable Entity wrapper around {@see apiError()} with the
-     * with the older meta shape — reads `options` off the current request
+     * field-error map pre-filled. Mirrors the shape Laravel's default
-     * when none are supplied.
+     * ValidationException renderer produces, so `assertJsonValidationErrors`
+     * keeps working — but the envelope also carries the unified `status`,
+     * `message`, `error` keys for the rest of the body.
      *
-     * Retained for backward compatibility — new code should use
+     *     return ResponseService::apiValidationError([
-     * {@see apiPaginated()}.
+     *         'book' => ['No copies of this book are currently available.'],
+     *     ]);
      *
-     * @param  \Illuminate\Contracts\Pagination\Paginator|mixed  $paginated
+     * @param  array<string, array<int, string>>  $errors
-     * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>  $resourceClass
+     * @param  array<string, mixed>  $extraMeta
-     * @param  array<string, mixed>  $meta
-     * @param  array<string, mixed>|null  $options
-     * @return array{data: mixed, meta: array<string, mixed>}
      */
-    public static function asPaginated(
+    public static function apiValidationError(
-        mixed $paginated,
+        array $errors,
-        string $resourceClass,
+        ?string $message = null,
-        array $meta = [],
+        array $extraMeta = [],
-        ?array $options = null,
+    ): JsonResponse {
-    ): array {
+        return self::apiError(
-        $resolvedOptions = $options ?? (is_array(request('options')) ? request('options') : []);
+            errorOrMessage: $message ?? 'The given data was invalid.',
-
+            status: Response::HTTP_UNPROCESSABLE_ENTITY,
-        $payload = self::response(
+            errors: $errors,
-            $resourceClass::collection($paginated),
+            type: 'ValidationException',
-            self::paginationMeta($paginated, $resolvedOptions),
+            extraMeta: $extraMeta,
         );
-
-        if ($meta) {
-            $payload['meta'] = array_merge($payload['meta'], $meta);
-        }
-
-        return $payload;
     }
 }