refacto: overhaul exception handling and expand negative test coverage

- Simplify `Api::handleErrorResponse` to align with Chroma v2 API consistency, utilizing direct JSON decoding and status code mapping (e.g., mapping 409 to `UniqueConstraintException`).
- Rename exception classes to remove redundant prefixes (e.g., `ChromaConnectionException` → `ConnectionException`).
- Standardize exception instantiation via the `ChromaException::create()` factory.
- Implement robust client-side validation in Collection methods for embeddings, `nResults`, IDs, and metadata.
- update `ApiTest`, `CollectionTest`, and `QueryFilteringTest` with comprehensive negative test scenarios.

Author: CodeWithKyrian

src/Api.php

@@ -4,8 +4,7 @@
 
 namespace Codewithkyrian\ChromaDB;
 
-use Codewithkyrian\ChromaDB\Exceptions\ChromaAuthorizationException;
-use Codewithkyrian\ChromaDB\Exceptions\ChromaConnectionException;
+use Codewithkyrian\ChromaDB\Exceptions\ConnectionException;
 use Codewithkyrian\ChromaDB\Exceptions\ChromaException;
 use Codewithkyrian\ChromaDB\Models\Collection;
 use Codewithkyrian\ChromaDB\Models\Database;
@@ -393,7 +392,7 @@ public function getCollectionItems(string $collectionId, string $database, strin
         $response = $this->sendRequest('POST', "/api/v2/tenants/$tenant/databases/$database/collections/$collectionId/get", [
             'json' => $request->toArray(),
         ]);
-
+ 
         $result = json_decode($response->getBody()->getContents(), true);
 
         return GetItemsResponse::fromArray($result);
@@ -435,72 +434,6 @@ public function queryCollectionItems(string $collectionId, string $database, str
         return QueryItemsResponse::fromArray($result);
     }
 
-
-    private function handleErrorResponse(ResponseInterface $response): void
-    {
-        $statusCode = $response->getStatusCode();
-
-        if ($statusCode === 401 || $statusCode === 403) {
-            throw new ChromaAuthorizationException($response->getReasonPhrase(), $statusCode);
-        }
-
-        $errorString = $response->getBody()->getContents();
-
-        if (preg_match('/(?<={"\"error\"\:\")([^"]*)/', $errorString, $matches)) {
-            $errorString = $matches[1];
-        }
-
-        $error = json_decode($errorString, true);
-
-        if ($error !== null) {
-
-            // If the structure is 'error' => 'NotFoundError("Collection not found")'
-            if (
-                preg_match(
-                    '/^(?P<error_type>\w+)\((?P<message>.*)\)$/',
-                    $error['error'] ?? '',
-                    $matches
-                )
-            ) {
-                if (isset($matches['message'])) {
-                    $error_type = $matches['error_type'] ?? 'UnknownError';
-                    $message = $matches['message'];
-
-                    // Remove trailing and leading quotes
-                    if (str_starts_with($message, "'") && str_ends_with($message, "'")) {
-                        $message = substr($message, 1, -1);
-                    }
-
-                    ChromaException::throwSpecific($message, $error_type, $statusCode);
-                }
-            }
-
-            // If the structure is 'detail' => 'Collection not found'
-            if (isset($error['detail'])) {
-                $message = $error['detail'];
-                $error_type = ChromaException::inferTypeFromMessage($message);
-
-
-                ChromaException::throwSpecific($message, $error_type, $statusCode);
-            }
-
-            // If the structure is {'error': 'Error Type', 'message' : 'Error message'}
-            if (isset($error['error']) && isset($error['message'])) {
-                ChromaException::throwSpecific($error['message'], $error['error'], $statusCode);
-            }
-
-            // If the structure is 'error' => 'Collection not found'
-            if (isset($error['error'])) {
-                $message = $error['error'];
-                $error_type = ChromaException::inferTypeFromMessage($message);
-
-                ChromaException::throwSpecific($message, $error_type, $statusCode);
-            }
-        }
-
-        throw new ChromaException($errorString ?: $response->getReasonPhrase(), $statusCode);
-    }
-
     private function sendRequest(string $method, string $path, array $options = []): ResponseInterface
     {
         $uri = $this->baseUri . $path;
@@ -524,7 +457,7 @@ private function sendRequest(string $method, string $path, array $options = []):
         try {
             $response = $this->client->sendRequest($request);
         } catch (ClientExceptionInterface $e) {
-            throw new ChromaConnectionException($e->getMessage(), $e->getCode());
+            throw new ConnectionException($e->getMessage(), $e->getCode());
         }
 
         if ($response->getStatusCode() >= 400) {
@@ -533,4 +466,19 @@ private function sendRequest(string $method, string $path, array $options = []):
 
         return $response;
     }
+
+    private function handleErrorResponse(ResponseInterface $response): void
+    {
+        $statusCode = $response->getStatusCode();
+        $body = json_decode($response->getBody()->getContents(), true);
+
+        $errorType = $body['error'] ?? 'UnknownError';
+        $message = $body['message'] ?? 'Unknown error occurred';
+
+        if ($statusCode === 409) {
+            $errorType = 'UniqueConstraintError';
+        }
+
+        throw ChromaException::create($message, $errorType, $statusCode);
+    }
 }

src/Client.php

@@ -6,7 +6,7 @@
 
 use Codewithkyrian\ChromaDB\Embeddings\EmbeddingFunction;
 use Codewithkyrian\ChromaDB\Api;
-use Codewithkyrian\ChromaDB\Exceptions\ChromaNotFoundException;
+use Codewithkyrian\ChromaDB\Exceptions\NotFoundException;
 use Codewithkyrian\ChromaDB\Models\Collection;
 use Codewithkyrian\ChromaDB\Requests\CreateDatabaseRequest;
 use Codewithkyrian\ChromaDB\Requests\CreateTenantRequest;
@@ -15,9 +15,9 @@
 class Client
 {
     public function __construct(
-        public readonly Api     $api,
-        public readonly string  $database,
-        public readonly string  $tenant,
+        public readonly Api $api,
+        public readonly string $database,
+        public readonly string $tenant,
     ) {
         $this->initDatabaseAndTenant();
     }
@@ -26,14 +26,14 @@ public function initDatabaseAndTenant(): void
     {
         try {
             $this->api->getTenant($this->tenant);
-        } catch (ChromaNotFoundException) {
+        } catch (NotFoundException) {
             $createTenantRequest = new CreateTenantRequest($this->tenant);
             $this->api->createTenant($createTenantRequest);
         }
 
         try {
             $this->api->getDatabase($this->database, $this->tenant);
-        } catch (ChromaNotFoundException) {
+        } catch (NotFoundException) {
             $createDatabaseRequest = new CreateDatabaseRequest($this->database);
             $this->api->createDatabase($this->tenant, $createDatabaseRequest);
         }
@@ -65,7 +65,7 @@ public function heartbeat(): int
      */
     public function listCollections(): array
     {
-        return  $this->api->listCollections($this->database, $this->tenant);
+        return $this->api->listCollections($this->database, $this->tenant);
     }
 
 
@@ -104,7 +104,7 @@ public function getOrCreateCollection(string $name, ?array $metadata = null, ?Em
     {
         $request = new CreateCollectionRequest($name, $metadata, true);
 
-        $collection =  $this->api->createCollection($this->database, $this->tenant, $request);
+        $collection = $this->api->createCollection($this->database, $this->tenant, $request);
 
         if ($embeddingFunction) {
             $collection->setEmbeddingFunction($embeddingFunction);

src/Exceptions/ChromaAuthorizationException.php

@@ -2,23 +2,21 @@
 
 declare(strict_types=1);
 
-
 namespace Codewithkyrian\ChromaDB\Exceptions;
 
 class ChromaException extends \Exception
 {
 
-    public static function throwSpecific(string $message, string $type, int $code)
+    public static function create(string $message, string $type, int $code): self
     {
-        throw match ($type) {
-            'NotFoundError' => new ChromaNotFoundException($message, $code),
-            'AuthorizationError' => new ChromaAuthorizationException($message, $code),
-            'ValueError' => new ChromaValueException($message, $code),
-            'UniqueConstraintError' => new ChromaUniqueConstraintException($message, $code),
-            'DimensionalityError' => new ChromaDimensionalityException($message, $code),
-            'InvalidCollection' => new ChromaInvalidCollectionException($message, $code),
-            'TypeError' => new ChromaTypeException($message, $code),
-            'InvalidArgumentError' => new ChromaInvalidArgumentException($message, $code),
+        return match ($type) {
+            'NotFoundError' => new NotFoundException($message, $code),
+            'ValueError' => new ValueException($message, $code),
+            'UniqueConstraintError' => new UniqueConstraintException($message, $code),
+            'DimensionalityError' => new DimensionalityException($message, $code),
+            'InvalidCollection' => new InvalidCollectionException($message, $code),
+            'TypeError' => new TypeException($message, $code),
+            'InvalidArgumentError' => new InvalidArgumentException($message, $code),
             default => new self($message, $code),
         };
     }

src/Exceptions/ChromaDimensionalityException.php

@@ -2,10 +2,9 @@
 
 declare(strict_types=1);
 
-
 namespace Codewithkyrian\ChromaDB\Exceptions;
 
-class ChromaTypeException extends ChromaException
+class ConnectionException extends ChromaException
 {
 
 }

src/Exceptions/ChromaException.php

@@ -2,10 +2,9 @@
 
 declare(strict_types=1);
 
-
 namespace Codewithkyrian\ChromaDB\Exceptions;
 
-class ChromaNotFoundException extends ChromaException
+class DimensionalityException extends ChromaException
 {
 
 }