Adds Extender API DTOs

src/Common/AbstractEnum.php

@@ -7,6 +7,7 @@
 use BadMethodCallException;
 use InvalidArgumentException;
 use ReflectionClass;
+use RuntimeException;
 
 /**
  * Abstract base class for enum-like behavior in PHP 7.4.
@@ -250,7 +251,7 @@ private static function getInstance(string $value, string $name): self
      * @since n.e.x.t
      *
      * @return array<string, string> Map of constant names to values.
-     * @throws \RuntimeException If invalid constant found.
+     * @throws RuntimeException If invalid constant found.
      */
     final protected static function getConstants(): array
     {
@@ -265,7 +266,7 @@ final protected static function getConstants(): array
             foreach ($constants as $name => $value) {
                 // Check if constant name follows uppercase snake_case pattern
                 if (!preg_match('/^[A-Z][A-Z0-9_]*$/', $name)) {
-                    throw new \RuntimeException(
+                    throw new RuntimeException(
                         sprintf(
                             'Invalid enum constant name "%s" in %s. Constants must be UPPER_SNAKE_CASE.',
                             $name,
@@ -276,7 +277,7 @@ final protected static function getConstants(): array
 
                 // Check if value is valid type
                 if (!is_string($value)) {
-                    throw new \RuntimeException(
+                    throw new RuntimeException(
                         sprintf(
                             'Invalid enum value type for constant %s::%s. ' .
                             'Only string values are allowed, %s given.',

src/Files/DTO/File.php

@@ -60,7 +60,7 @@ class File extends AbstractDataValueObject
      *
      * @param string $file The file string (URL, base64 data, or local path).
      * @param string|null $mimeType The MIME type of the file (optional).
-     * @throws \InvalidArgumentException If the file format is invalid or MIME type cannot be determined.
+     * @throws InvalidArgumentException If the file format is invalid or MIME type cannot be determined.
      */
     public function __construct(string $file, ?string $mimeType = null)
     {
@@ -75,7 +75,7 @@ public function __construct(string $file, ?string $mimeType = null)
      *
      * @param string $file The file string to process.
      * @param string|null $providedMimeType The explicitly provided MIME type.
-     * @throws \InvalidArgumentException If the file format is invalid or MIME type cannot be determined.
+     * @throws InvalidArgumentException If the file format is invalid or MIME type cannot be determined.
      */
     private function detectAndProcessFile(string $file, ?string $providedMimeType): void
     {
@@ -110,7 +110,7 @@ private function detectAndProcessFile(string $file, ?string $providedMimeType):
         // Check if it's plain base64
         if (preg_match('/^[A-Za-z0-9+\/]*={0,2}$/', $file)) {
             if ($providedMimeType === null) {
-                throw new \InvalidArgumentException(
+                throw new InvalidArgumentException(
                     'MIME type is required when providing plain base64 data without data URI format.'
                 );
             }
@@ -120,7 +120,7 @@ private function detectAndProcessFile(string $file, ?string $providedMimeType):
             return;
         }
 
-        throw new \InvalidArgumentException(
+        throw new InvalidArgumentException(
             'Invalid file provided. Expected URL, base64 data, or valid local file path.'
         );
     }
@@ -146,14 +146,14 @@ private function isUrl(string $string): bool
      *
      * @param string $filePath The path to the local file.
      * @return string The base64-encoded file data.
-     * @throws \RuntimeException If the file cannot be read.
+     * @throws RuntimeException If the file cannot be read.
      */
     private function convertFileToBase64(string $filePath): string
     {
         $fileContent = @file_get_contents($filePath);
 
         if ($fileContent === false) {
-            throw new \RuntimeException(
+            throw new RuntimeException(
                 sprintf('Unable to read file: %s', $filePath)
             );
         }
@@ -294,7 +294,7 @@ public function isText(): bool
      * @param string|null $extractedMimeType The MIME type extracted from data URI.
      * @param string|null $pathOrUrl The file path or URL to extract extension from.
      * @return MimeType The determined MIME type.
-     * @throws \InvalidArgumentException If MIME type cannot be determined.
+     * @throws InvalidArgumentException If MIME type cannot be determined.
      */
     private function determineMimeType(
         ?string $providedMimeType,
@@ -326,14 +326,14 @@ private function determineMimeType(
             if (!empty($extension)) {
                 try {
                     return MimeType::fromExtension($extension);
-                } catch (\InvalidArgumentException $e) {
+                } catch (InvalidArgumentException $e) {
                     // Extension not recognized, continue to error
                     unset($e);
                 }
             }
         }
 
-        throw new \InvalidArgumentException(
+        throw new InvalidArgumentException(
             'Unable to determine MIME type. Please provide it explicitly.'
         );
     }

src/Files/ValueObjects/MimeType.php

@@ -4,6 +4,8 @@
 
 namespace WordPress\AiClient\Files\ValueObjects;
 
+use InvalidArgumentException;
+
 /**
  * Value object representing a MIME type.
  *
@@ -115,12 +117,12 @@ final class MimeType
      * @since n.e.x.t
      *
      * @param string $value The MIME type value.
-     * @throws \InvalidArgumentException If the MIME type is invalid.
+     * @throws InvalidArgumentException If the MIME type is invalid.
      */
     public function __construct(string $value)
     {
         if (!self::isValid($value)) {
-            throw new \InvalidArgumentException(
+            throw new InvalidArgumentException(
                 sprintf('Invalid MIME type: %s', $value)
             );
         }
@@ -135,14 +137,14 @@ public function __construct(string $value)
      *
      * @param string $extension The file extension (without the dot).
      * @return self The MimeType instance.
-     * @throws \InvalidArgumentException If the extension is not recognized.
+     * @throws InvalidArgumentException If the extension is not recognized.
      */
     public static function fromExtension(string $extension): self
     {
         $extension = strtolower($extension);
 
         if (!isset(self::$extensionMap[$extension])) {
-            throw new \InvalidArgumentException(
+            throw new InvalidArgumentException(
                 sprintf('Unknown file extension: %s', $extension)
             );
         }
@@ -245,7 +247,7 @@ public function equals($other): bool
             return $this->value === strtolower($other);
         }
 
-        throw new \InvalidArgumentException(
+        throw new InvalidArgumentException(
             sprintf('Invalid MIME type comparison: %s', gettype($other))
         );
     }

src/Providers/DTO/ProviderMetadata.php

@@ -0,0 +1,158 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\DTO;
+
+use WordPress\AiClient\Common\AbstractDataValueObject;
+use WordPress\AiClient\Providers\Enums\ProviderTypeEnum;
+
+/**
+ * Represents metadata about an AI provider.
+ *
+ * This class contains information about an AI provider, including its
+ * unique identifier, display name, and type (cloud, server, or client).
+ *
+ * @since n.e.x.t
+ *
+ * @phpstan-type ProviderMetadataArrayShape array{
+ *     id: string,
+ *     name: string,
+ *     type: string
+ * }
+ *
+ * @extends AbstractDataValueObject<ProviderMetadataArrayShape>
+ */
+class ProviderMetadata extends AbstractDataValueObject
+{
+    public const KEY_ID = 'id';
+    public const KEY_NAME = 'name';
+    public const KEY_TYPE = 'type';
+
+    /**
+     * @var string The provider's unique identifier.
+     */
+    protected string $id;
+
+    /**
+     * @var string The provider's display name.
+     */
+    protected string $name;
+
+    /**
+     * @var ProviderTypeEnum The provider type.
+     */
+    protected ProviderTypeEnum $type;
+
+    /**
+     * Constructor.
+     *
+     * @since n.e.x.t
+     *
+     * @param string $id The provider's unique identifier.
+     * @param string $name The provider's display name.
+     * @param ProviderTypeEnum $type The provider type.
+     */
+    public function __construct(string $id, string $name, ProviderTypeEnum $type)
+    {
+        $this->id = $id;
+        $this->name = $name;
+        $this->type = $type;
+    }
+
+    /**
+     * Gets the provider's unique identifier.
+     *
+     * @since n.e.x.t
+     *
+     * @return string The provider ID.
+     */
+    public function getId(): string
+    {
+        return $this->id;
+    }
+
+    /**
+     * Gets the provider's display name.
+     *
+     * @since n.e.x.t
+     *
+     * @return string The provider name.
+     */
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    /**
+     * Gets the provider type.
+     *
+     * @since n.e.x.t
+     *
+     * @return ProviderTypeEnum The provider type.
+     */
+    public function getType(): ProviderTypeEnum
+    {
+        return $this->type;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     */
+    public static function getJsonSchema(): array
+    {
+        return [
+            'type' => 'object',
+            'properties' => [
+                self::KEY_ID => [
+                    'type' => 'string',
+                    'description' => 'The provider\'s unique identifier.',
+                ],
+                self::KEY_NAME => [
+                    'type' => 'string',
+                    'description' => 'The provider\'s display name.',
+                ],
+                self::KEY_TYPE => [
+                    'type' => 'string',
+                    'enum' => ProviderTypeEnum::getValues(),
+                    'description' => 'The provider type (cloud, server, or client).',
+                ],
+            ],
+            'required' => [self::KEY_ID, self::KEY_NAME, self::KEY_TYPE],
+        ];
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     *
+     * @return ProviderMetadataArrayShape
+     */
+    public function toArray(): array
+    {
+        return [
+            self::KEY_ID => $this->id,
+            self::KEY_NAME => $this->name,
+            self::KEY_TYPE => $this->type->value,
+        ];
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     */
+    public static function fromArray(array $array): self
+    {
+        static::validateFromArrayData($array, [self::KEY_ID, self::KEY_NAME, self::KEY_TYPE]);
+
+        return new self(
+            $array[self::KEY_ID],
+            $array[self::KEY_NAME],
+            ProviderTypeEnum::from($array[self::KEY_TYPE])
+        );
+    }
+}