✨ add support for Client v2

.github/workflows/_test-code-samples.yml

@@ -30,4 +30,4 @@ jobs:
         env:
           MINDEE_API_KEY: ${{ secrets.MINDEE_API_KEY_SE_TESTS }}
         run: |
-          ./tests/test_code_samples.sh ${{ secrets.MINDEE_ACCOUNT_SE_TESTS }} ${{ secrets.MINDEE_ENDPOINT_SE_TESTS }} ${{ secrets.MINDEE_API_KEY_SE_TESTS }}
+          ./tests/test_code_samples.sh ${{ secrets.MINDEE_ACCOUNT_SE_TESTS }} ${{ secrets.MINDEE_ENDPOINT_SE_TESTS }} ${{ secrets.MINDEE_API_KEY_SE_TESTS }} ${{ secrets.MINDEE_V2_SE_TESTS_API_KEY }} ${{ secrets.MINDEE_V2_SE_TESTS_FINDOC_MODEL_ID }}

.github/workflows/_test-integrations.yml

@@ -12,6 +12,8 @@ env:
   MINDEE_ENDPOINT_SE_TESTS: ${{ secrets.MINDEE_ENDPOINT_SE_TESTS }}
   MINDEE_API_KEY: ${{ secrets.MINDEE_API_KEY_SE_TESTS }}
   WORKFLOW_ID: ${{ secrets.WORKFLOW_ID_SE_TESTS }}
+  MINDEE_V2_API_KEY: ${{ secrets.MINDEE_V2_SE_TESTS_API_KEY }}
+  MINDEE_V2_FINDOC_MODEL_ID: ${{ secrets.MINDEE_V2_SE_TESTS_FINDOC_MODEL_ID }}
 
 jobs:
   integration-tests-ubuntu:

.github/workflows/pull-request.yml

@@ -3,21 +3,25 @@ name: Pull Request
 on:
   pull_request:
 
+permissions:
+  contents: read
+  pull-requests: read
+
 jobs:
   static-analysis:
-    uses: mindee/mindee-api-php/.github/workflows/_static-analysis.yml@main
+    uses: ./.github/workflows/_static-analysis.yml
   static-dependency-checks:
-    uses: mindee/mindee-api-php/.github/workflows/_static-dependency-checks.yml@main
+    uses: ./.github/workflows/_static-dependency-checks.yml
     needs: static-analysis
   test-units:
-    uses: mindee/mindee-api-php/.github/workflows/_test-units.yml@main
+    uses: ./.github/workflows/_test-units.yml
     needs: static-analysis
     secrets: inherit
   test-integrations:
-    uses: mindee/mindee-api-php/.github/workflows/_test-integrations.yml@main
+    uses: ./.github/workflows/_test-integrations.yml
     needs: test-units
     secrets: inherit
   test-code-samples:
-    uses: mindee/mindee-api-php/.github/workflows/_test-code-samples.yml@main
+    uses: ./.github/workflows/_test-code-samples.yml
     needs: test-units
     secrets: inherit

docs/code_samples/default_v2.txt

@@ -0,0 +1,33 @@
+<?php
+
+use Mindee\ClientV2;
+use Mindee\Input\InferenceParameters;
+use Mindee\Input\PathInput;
+use Mindee\Error\MindeeException;
+
+$apiKey = "MY_API_KEY";
+$filePath = "/path/to/the/file.ext";
+$modelId = "MY_MODEL_ID";
+
+// Init a new client
+$mindeeClient = new ClientV2($apiKey);
+
+// Set inference parameters
+// Note: modelId is mandatory.
+$inferenceParams = new InferenceParameters(
+    $modelId,
+    // If set to `true`, will enable Retrieval-Augmented Generation.
+    false
+);
+
+// Load a file from disk
+$inputSource = new PathInput($filePath);
+
+// Upload the file
+$response = $mindeeClient->enqueueAndGetInference(
+    $inputSource,
+    $inferenceParams
+);
+
+// Print a summary of the response
+echo strval($response->inference);

src/Client.php

@@ -226,7 +226,7 @@ public function createEndpoint(string $endpointName, string $accountName, ?strin
      */
     private function cutDocPages(LocalInputSource $inputDoc, PageOptions $pageOptions)
     {
-        $inputDoc->processPDF($pageOptions->operation, $pageOptions->onMinPage, $pageOptions->pageIndexes);
+        $inputDoc->applyPageOptions($pageOptions);
     }
 
     /**

src/ClientV2.php

@@ -0,0 +1,133 @@
+<?php
+
+namespace Mindee;
+
+use Mindee\Error\MindeeException;
+use Mindee\Http\MindeeApiV2;
+use Mindee\Input\InferenceParameters;
+use Mindee\Input\InputSource;
+use Mindee\Parsing\V2\InferenceResponse;
+use Mindee\Parsing\V2\JobResponse;
+
+/**
+ * Mindee Client V2.
+ */
+class ClientV2
+{
+    /**
+     * @var MindeeApiV2 Mindee API V2.
+     */
+    protected MindeeApiV2 $mindeeApi;
+
+    /**
+     * Mindee Client V2.
+     *
+     * @param string|null $apiKey Optional API key. Will fall back to environment variable if not provided.
+     */
+    public function __construct(?string $apiKey = null)
+    {
+        $this->mindeeApi = new MindeeApiV2($apiKey ?: getenv('MINDEE_V2_API_KEY'));
+    }
+
+    /**
+     * Send the document to an asynchronous endpoint and return its ID in the queue.
+     *
+     * @param InputSource         $inputSource File to parse.
+     * @param InferenceParameters $params      Parameters relating to prediction options.
+     * @return JobResponse A JobResponse containing the job (queue) corresponding to a document.
+     * @throws MindeeException Throws if the input document is not provided.
+     * @category Asynchronous
+     */
+    public function enqueueInference(
+        InputSource $inputSource,
+        InferenceParameters $params
+    ): JobResponse {
+        return $this->mindeeApi->reqPostInferenceEnqueue($inputSource, $params);
+    }
+
+    /**
+     * Retrieves an inference.
+     *
+     * @param string $inferenceId ID of the queue to poll.
+     * @return InferenceResponse An InferenceResponse containing a Job.
+     * @category Asynchronous
+     */
+    public function getInference(string $inferenceId): InferenceResponse
+    {
+        return $this->mindeeApi->reqGetInference($inferenceId);
+    }
+
+    /**
+     * Get the status of an inference that was previously enqueued.
+     * Can be used for polling.
+     *
+     * @param string $jobId ID of the queue to poll.
+     * @return JobResponse A JobResponse containing a Job, which also contains a Document if the parsing is complete.
+     * @category Asynchronous
+     */
+    public function getJob(string $jobId): JobResponse
+    {
+        return $this->mindeeApi->reqGetJob($jobId);
+    }
+
+    /**
+     * Send a document to an endpoint and poll the server until the result is sent or
+     * until the maximum number of tries is reached.
+     *
+     * @param InputSource         $inputDoc Input document to parse.
+     * @param InferenceParameters $params   Parameters relating to prediction options.
+     * @return InferenceResponse A response containing parsing results.
+     * @throws MindeeException Throws if enqueueing fails, job fails, or times out.
+     * @category Synchronous
+     */
+    public function enqueueAndGetInference(
+        InputSource $inputDoc,
+        InferenceParameters $params
+    ): InferenceResponse {
+        $pollingOptions = $params->pollingOptions;
+
+        $enqueueResponse = $this->enqueueInference($inputDoc, $params);
+
+        if (empty($enqueueResponse->job->id)) {
+            error_log("Failed enqueueing:\n" . json_encode($enqueueResponse));
+            throw new MindeeException("Enqueueing of the document failed.");
+        }
+
+        $queueId = $enqueueResponse->job->id;
+        error_log("Successfully enqueued document with job id: " . $queueId);
+
+        sleep($pollingOptions->initialDelaySec);
+        $retryCounter = 1;
+        $pollResults = $this->getJob($queueId);
+
+        while ($retryCounter < $pollingOptions->maxRetries) {
+            if ($pollResults->job->status === "Failed") {
+                break;
+            }
+            if ($pollResults->job->status === "Processed") {
+                return $this->getInference($pollResults->job->id);
+            }
+
+            error_log(
+                "Polling server for parsing result with queueId: " . $queueId .
+                ". Attempt n°" . $retryCounter . "/" . $pollingOptions->maxRetries .
+                ". Job status: " . $pollResults->job->status
+            );
+
+            sleep($pollingOptions->delaySec);
+            $pollResults = $this->getJob($queueId);
+            $retryCounter++;
+        }
+
+        if ($pollResults->job->error) {
+            throw new MindeeException(
+                "Job failed: " . ($pollResults->job->error->detail ?? 'Unknown error')
+            );
+        }
+
+        throw new MindeeException(
+            "Asynchronous parsing request timed out after " .
+            ($pollingOptions->delaySec * $retryCounter) . " seconds"
+        );
+    }
+}

src/Error/MindeeV2HttpException.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Mindee\Error;
+
+/**
+ * Exceptions relating to HTTP errors for the V2 API.
+ */
+class MindeeV2HttpException extends MindeeException
+{
+    /**
+     * @var integer Status code as sent by the server.
+     */
+    public int $status;
+    /**
+     * @var string|null Details on the exception.
+     */
+    public ?string $detail;
+
+    /**
+     * @param integer     $status HTTP status code, defaults to -1 if not set.
+     * @param string|null $detail Optional details on the exception.
+     */
+    public function __construct(int $status, string $detail = null)
+    {
+        parent::__construct("HTTP Error $status - $detail");
+        $this->status = $status;
+        $this->detail = $detail;
+    }
+}

src/Http/BaseApi.php

@@ -96,7 +96,7 @@ protected function setTimeout(string $value)
     }
 
     /**
-     * Sets values from environment if needed.
+     * Sets values from environment, if needed.
      *
      * @return void
      */
@@ -115,7 +115,6 @@ protected function setFromEnv()
         }
     }
 
-
     /**
      * Sets the API key.
      *
@@ -144,18 +143,4 @@ public function __construct(
         $this->requestTimeout = TIMEOUT_DEFAULT;
         $this->setFromEnv();
     }
-
-    /**
-     * Sets the URL root.
-     *
-     * @param string $urlSuffix The URL suffix to be added after the root url.
-     * @return void
-     */
-    public function updateUrlRoot(string $urlSuffix): void
-    {
-        $this->urlRoot = rtrim(
-            $this->baseUrl,
-            "/"
-        ) . $urlSuffix;
-    }
 }