✨ 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.
@@ -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;
@@ -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/PaginationMetadata.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mindee\V2\Parsing\Search;
+
+use Stringable;
+
+/**
+ * Pagination metadata.
+ */
+class PaginationMetadata 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 PaginationMetadata Pagination metadata for the search results.
+     */
+    public PaginationMetadata $paginationMetadata;
+
+    /**
+     * @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->paginationMetadata = new PaginationMetadata($rawResponse['pagination']);
+    }
+
+    /**
+     * @return string String representation.
+     */
+    public function __toString(): string
+    {
+        return implode("\n", [
+            'Models',
+            '######',
+            (string) $this->models,
+            'Pagination Metadata',
+            '###################',
+            (string) $this->paginationMetadata,
+            '',
+        ]);
+    }
+}

tests/V2/Parsing/SearchResponseTest.php

@@ -0,0 +1,44 @@
+<?php
+
+
+declare(strict_types=1);
+
+namespace V2\Parsing;
+
+use DateTime;
+use Mindee\V2\Parsing\Error\ErrorItem;
+use Mindee\V2\Parsing\Error\ErrorResponse;
+use Mindee\V2\Parsing\Job\JobResponse;
+use Mindee\V2\Parsing\Search\SearchModel;
+use Mindee\V2\Parsing\Search\SearchResponse;
+use PHPUnit\Framework\TestCase;
+use TestingUtilities;
+
+require_once(__DIR__ . "/../../TestingUtilities.php");
+
+/**
+ * InferenceV2 – field integrity checks
+ */
+class SearchResponseTest extends TestCase
+{
+    public function testSearchResponse(): void
+    {
+        $fullPath = TestingUtilities::getV2DataDir() . "/search/models.json";
+        $content = file_get_contents($fullPath);
+        $json = json_decode($content, true);
+        $response = new SearchResponse($json);
+        self::assertNotEmpty($response->models);
+        foreach ($response->models as $model) {
+            self::assertInstanceOf(SearchModel::class, $model);
+            self::assertNotEmpty($model->id);
+            self::assertNotEmpty($model->name);
+        }
+        self::assertCount(2, $response->models[0]->webhooks);
+        self::assertEquals("https://failure.mindee.com", $response->models[0]->webhooks[0]->url);
+
+        self::assertEquals(50, $response->paginationMetadata->perPage);
+        self::assertEquals(1, $response->paginationMetadata->page);
+        self::assertGreaterThanOrEqual(5, $response->paginationMetadata->totalItems);
+        self::assertEquals(1, $response->paginationMetadata->totalPages);
+    }
+}