Build centralized error message extraction utility

Add ErrorMessageExtractor utility to centralize parsing of common API error response formats across exception classes. Handles standard patterns like { "error": { "message": "..." } }, { "error": "..." }, and { "message": "..." }.

Implement fromPsrRequest static factory method in Request DTO to support PSR-7 to internal DTO conversion for exception context storage.

Author: Mohamed Khaled

src/Providers/Http/DTO/Request.php

@@ -5,6 +5,7 @@
 namespace WordPress\AiClient\Providers\Http\DTO;
 
 use JsonException;
+use Psr\Http\Message\RequestInterface;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
 use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Providers\Http\Collections\HeadersCollection;
@@ -355,4 +356,29 @@ public static function fromArray(array $array): self
             $array[self::KEY_BODY] ?? null
         );
     }
+
+    /**
+     * Creates a Request instance from a PSR-7 RequestInterface.
+     *
+     * @since n.e.x.t
+     *
+     * @param RequestInterface $psrRequest The PSR-7 request to convert.
+     * @return self A new Request instance.
+     * @throws InvalidArgumentException If the HTTP method is not supported.
+     */
+    public static function fromPsrRequest(RequestInterface $psrRequest): self
+    {
+        $method = HttpMethodEnum::from($psrRequest->getMethod());
+        $uri = (string) $psrRequest->getUri();
+
+        // Convert PSR-7 headers to array format expected by our constructor
+        /** @var array<string, list<string>> $headers */
+        $headers = $psrRequest->getHeaders();
+
+        // Get body content
+        $body = $psrRequest->getBody()->getContents();
+        $bodyOrData = !empty($body) ? $body : null;
+
+        return new self($method, $uri, $headers, $bodyOrData);
+    }
 }

src/Providers/Http/Utilities/ErrorMessageExtractor.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Http\Utilities;
+
+/**
+ * Utility for extracting error messages from API response data.
+ *
+ * Centralizes the logic for parsing common API error response formats
+ * to avoid code duplication across exception classes.
+ *
+ * @since n.e.x.t
+ */
+class ErrorMessageExtractor
+{
+    /**
+     * Extracts error message from API response data.
+     *
+     * Handles common error response formats:
+     * - { "error": { "message": "Error text" } }
+     * - { "error": "Error text" }
+     * - { "message": "Error text" }
+     *
+     * @since n.e.x.t
+     *
+     * @param mixed $data The response data to extract error message from.
+     * @return string|null The extracted error message, or null if none found.
+     */
+    public static function extractFromResponseData($data): ?string
+    {
+        if (!is_array($data)) {
+            return null;
+        }
+
+        // Handle { "error": { "message": "Error text" } }
+        if (
+            isset($data['error']) &&
+            is_array($data['error']) &&
+            isset($data['error']['message']) &&
+            is_string($data['error']['message'])
+        ) {
+            return $data['error']['message'];
+        }
+
+        // Handle { "error": "Error text" }
+        if (isset($data['error']) && is_string($data['error'])) {
+            return $data['error'];
+        }
+
+        // Handle { "message": "Error text" }
+        if (isset($data['message']) && is_string($data['message'])) {
+            return $data['message'];
+        }
+
+        return null;
+    }
+}