✨ add support for model search

src/V2/Client.php

@@ -12,6 +12,7 @@
 use Mindee\V2\Http\MindeeApiV2;
 use Mindee\V2\Parsing\Inference\BaseResponse;
 use Mindee\V2\Parsing\Job\JobResponse;
+use Mindee\V2\Parsing\Search\SearchResponse;
 
 /**
  * Mindee Client V2.
@@ -32,7 +33,7 @@ class Client
      */
     public function __construct(?string $apiKey = null)
     {
-        $this->mindeeApi = new MindeeApiV2($apiKey ?: getenv('MINDEE_V2_API_KEY'));
+        $this->mindeeApi = new MindeeApiV2($apiKey ?: (getenv('MINDEE_V2_API_KEY') ?: null));
     }
 
     /**
@@ -159,4 +160,15 @@ public function enqueueAndGetResult(
             . ($pollingOptions->delaySec * $retryCounter) . " seconds"
         );
     }
+
+    /**
+     * Searches for a list of available models for the given API key.
+     * @param string|null $modelName Optional model name to filter by.
+     * @param string|null $modelType Optional model type to filter by.
+     * @return SearchResponse The list of models matching the criteria.
+     */
+    public function searchModels(?string $modelName = null, ?string $modelType = null): SearchResponse
+    {
+        return $this->mindeeApi->searchModels($modelName, $modelType);
+    }
 }

src/V2/Http/MindeeApiV2.php

@@ -22,6 +22,7 @@
 use Mindee\V2\Parsing\Error\ErrorResponse;
 use Mindee\V2\Parsing\Inference\BaseResponse;
 use Mindee\V2\Parsing\Job\JobResponse;
+use Mindee\V2\Parsing\Search\SearchResponse;
 use ReflectionClass;
 use ReflectionException;
 use ReflectionProperty;
@@ -106,7 +107,7 @@ public function __construct(?string $apiKey)
             throw new MindeeException(
                 "Missing API key for call,"
                 . " check your Client configuration.You can set this using the "
-                . API_KEY_ENV_NAME . ' environment variable.',
+                . API_V2_KEY_ENV_NAME . ' environment variable.',
                 ErrorCode::USER_INPUT_ERROR
             );
         }
@@ -386,4 +387,44 @@ private function checkValidResponse(array $result): void
             throw new MindeeV2HttpUnknownException(json_encode($result, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT));
         }
     }
+
+    /**
+     * @return array<string, integer|float|string|bool|null|array<mixed>> Server response.
+     */
+    private function reqGetSearchModels(?string $modelName = null, ?string $modelType = null): array
+    {
+        $url = $this->baseUrl . "/v2/search/models";
+        $params = [];
+        if ($modelName) {
+            $params['name'] = $modelName;
+        }
+        if ($modelType) {
+            $params['model_type'] = $modelType;
+        }
+        if (!empty($params)) {
+            $url .= '?' . http_build_query($params);
+        }
+
+        $ch = $this->initChannel();
+        curl_setopt($ch, CURLOPT_URL, $url);
+        curl_setopt($ch, CURLOPT_HTTPGET, true);
+
+        $resp = [
+            'data' => curl_exec($ch),
+            'code' => curl_getinfo($ch, CURLINFO_HTTP_CODE),
+        ];
+        curl_close($ch);
+        return $resp;
+    }
+
+    /**
+     * Retrieves a list of models based on criteria.
+     * @param string|null $modelName Optional model name to filter by.
+     * @param string|null $modelType Optional model type to filter by.
+     * @return SearchResponse The list of models matching the criteria.
+     */
+    public function searchModels(?string $modelName = null, ?string $modelType = null): SearchResponse
+    {
+        return $this->processResponse(SearchResponse::class, $this->reqGetSearchModels($modelName, $modelType));
+    }
 }

src/V2/Parsing/Search/ModelWebhook.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mindee\V2\Parsing\Search;
+
+use Stringable;
+
+/**
+ * Model webhook information.
+ */
+class ModelWebhook implements Stringable
+{
+    /**
+     * @var string ID of the webhook.
+     */
+    public string $id;
+    /**
+     * @var string Name of the webhook.
+     */
+    public string $name;
+    /**
+     * @var string URL of the webhook.
+     */
+    public string $url;
+
+    /**
+     * @param array<string, int|float|string|bool|null|array<array-key, mixed>> $rawResponse
+     */
+    public function __construct(array $rawResponse)
+    {
+        $this->id = $rawResponse['id'];
+        $this->name = $rawResponse['name'];
+        $this->url = $rawResponse['url'];
+    }
+
+    public function __toString(): string
+    {
+        return ":Name: $this->name\n"
+            . ":ID: $this->id\n"
+            . ":URL: $this->url\n";
+    }
+}

src/V2/Parsing/Search/Pagination.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mindee\V2\Parsing\Search;
+
+use Stringable;
+
+/**
+ * Pagination metadata.
+ */
+class Pagination implements Stringable
+{
+    /**
+     * @var integer Number of items per page.
+     */
+    public int $perPage;
+    /**
+     * @var integer 1-indexed page number.
+     */
+    public int $page;
+    /**
+     * @var integer Total number of items.
+     */
+    public int $totalItems;
+    /**
+     * @var integer Total number of pages.
+     */
+    public int $totalPages;
+
+    /**
+     * @param array<string, int|float|string|bool|null|array<array-key, mixed>> $rawResponse Raw server response array.
+     */
+    public function __construct(array $rawResponse)
+    {
+        $this->perPage = $rawResponse['per_page'];
+        $this->page = $rawResponse['page'];
+        $this->totalItems = $rawResponse['total_items'];
+        $this->totalPages = $rawResponse['total_pages'];
+    }
+
+    /**
+     * @return string String representation.
+     */
+    public function __toString(): string
+    {
+        return ":Per Page: $this->perPage\n"
+            . ":Page: $this->page\n"
+            . ":Total Items: $this->totalItems\n"
+            . ":Total Pages: $this->totalPages\n";
+    }
+}

src/V2/Parsing/Search/SearchModel.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mindee\V2\Parsing\Search;
+
+use Stringable;
+
+/**
+ * Individual model information.
+ */
+class SearchModel implements Stringable
+{
+    /**
+     * @var string Model ID.
+     */
+    public string $id;
+    /**
+     * @var string Model name.
+     */
+    public string $name;
+    /**
+     * @var string Model type.
+     */
+    public string $modelType;
+    /**
+     * @var array<ModelWebhook> List of webhooks associated with the model.
+     */
+    public array $webhooks;
+
+    /**
+     * @param array<string, int|float|string|bool|null|array<array-key, mixed>> $rawResponse Raw server response array.
+     */
+    public function __construct(array $rawResponse)
+    {
+        $this->id = $rawResponse['id'];
+        $this->name = $rawResponse['name'];
+        $this->modelType = $rawResponse['model_type'];
+        $this->webhooks = array_map(
+            static fn($webhook) => new ModelWebhook($webhook),
+            $rawResponse['webhooks'] ?? []
+        );
+    }
+
+    /**
+     * @return string String representation.
+     */
+    public function __toString(): string
+    {
+        return ":Name: $this->name\n"
+            . ":ID: $this->id\n"
+            . ":Model Type: $this->modelType\n"
+            . ":Webhooks: " . implode(', ', array_map(static fn($webhook) => $webhook->name, $this->webhooks)) . "\n";
+    }
+}

src/V2/Parsing/Search/SearchModels.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mindee\V2\Parsing\Search;
+
+use ArrayObject;
+use Stringable;
+
+use function count;
+
+/**
+ * Array of search models.
+ * @extends ArrayObject<int, SearchModel>
+ */
+class SearchModels extends ArrayObject implements Stringable
+{
+    /**
+     * @param array<array<string, int|float|string|bool|null|array<array-key, mixed>>> $prediction Raw prediction.
+     */
+    public function __construct(array $prediction)
+    {
+        $models = array_map(static fn($entry) => new SearchModel($entry), $prediction);
+
+        parent::__construct($models);
+    }
+
+    /**
+     * Default string representation.
+     */
+    public function __toString(): string
+    {
+        if ($this->count() === 0) {
+            return "\n";
+        }
+
+        $lines = [];
+        foreach ($this as $model) {
+            $lines[] = "* :Name: " . $model->name;
+            $lines[] = "  :ID: " . $model->id;
+            $lines[] = "  :Model Type: " . $model->modelType;
+            $lines[] = "  :Webhooks: " . count($model->webhooks);
+        }
+
+        return implode("\n", $lines) . "\n";
+    }
+}

src/V2/Parsing/Search/SearchResponse.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mindee\V2\Parsing\Search;
+
+use Mindee\V2\Parsing\Inference\BaseResponse;
+use Stringable;
+
+/**
+ * Models search response.
+ */
+class SearchResponse extends BaseResponse implements Stringable
+{
+    /**
+     * @var SearchModels Parsed search payload.
+     */
+    public SearchModels $models;
+
+    /**
+     * @var Pagination Pagination metadata for the search results.
+     */
+    public Pagination $pagination;
+
+    /**
+     * @param array<string, int|float|string|bool|null|array<array-key, mixed>> $rawResponse Raw server response array.
+     */
+    public function __construct(array $rawResponse)
+    {
+        parent::__construct($rawResponse);
+        $this->models = new SearchModels($rawResponse['models']);
+        $this->pagination = new Pagination($rawResponse['pagination']);
+    }
+
+    /**
+     * @return string String representation.
+     */
+    public function __toString(): string
+    {
+        return implode("\n", [
+            'Models',
+            '######',
+            (string) $this->models,
+            'Pagination Metadata',
+            '###################',
+            (string) $this->pagination,
+            '',
+        ]);
+    }
+}

tests/V2/ClientV2Test.php

@@ -139,6 +139,7 @@ public function testInferenceLoadsLocally(): void
             'Supplier name mismatch'
         );
     }
+
     public function testInvalidBaseUrlRaisesMindeeException(): void
     {
         $this->expectException(MindeeException::class);
@@ -159,4 +160,21 @@ public function testInvalidBaseUrlRaisesMindeeException(): void
             }
         }
     }
+
+    public function testInvalidApiKeyRaisesMindeeException(): void
+    {
+        $original = getenv('MINDEE_V2_API_KEY') ?: null;
+        putenv('MINDEE_V2_API_KEY=');
+        $this->expectException(MindeeException::class);
+        $this->expectExceptionMessage('Missing API key for call, check your Client configuration.You can set this using the MINDEE_V2_API_KEY environment variable.');
+        try {
+            $client = new Client();
+        } finally {
+            if (null === $original) {
+                putenv('MINDEE_V2_API_KEY');
+            } else {
+                putenv('MINDEE_V2_API_KEY=' . $original);
+            }
+        }
+    }
 }