Add enforce_handoff configuration with validation for IDV session creation

src/DocScan/Session/Create/SdkConfig.php

@@ -4,6 +4,7 @@
 
 namespace Yoti\DocScan\Session\Create;
 
+use Yoti\DocScan\Exception\DocScanException;
 use Yoti\Util\Json;
 
 class SdkConfig implements \JsonSerializable
@@ -58,6 +59,11 @@ class SdkConfig implements \JsonSerializable
      */
     private $allowHandoff;
 
+    /**
+     * @var bool|null
+     */
+    private $enforceHandoff;
+
     /**
      * @var AttemptsConfiguration|null
      */
@@ -94,6 +100,7 @@ class SdkConfig implements \JsonSerializable
      * @param string|null $errorUrl
      * @param string|null $privacyPolicyUrl
      * @param bool|null $allowHandoff
+     * @param bool|null $enforceHandoff
      * @param array<string, int>|null $idDocumentTextDataExtractionRetriesConfig
      * @param string|null $biometricConsentFlow
      * @param string|null $darkMode
@@ -111,6 +118,7 @@ public function __construct(
         ?string $errorUrl,
         ?string $privacyPolicyUrl = null,
         ?bool $allowHandoff = null,
+        ?bool $enforceHandoff = null,
         ?array $idDocumentTextDataExtractionRetriesConfig = null,
         ?string $biometricConsentFlow = null,
         ?string $darkMode = null,
@@ -127,6 +135,8 @@ public function __construct(
         $this->errorUrl = $errorUrl;
         $this->privacyPolicyUrl = $privacyPolicyUrl;
         $this->allowHandoff = $allowHandoff;
+        $this->validateEnforceHandoff($allowHandoff, $enforceHandoff);
+        $this->enforceHandoff = $enforceHandoff;
         if (!is_null($idDocumentTextDataExtractionRetriesConfig)) {
             $this->attemptsConfiguration = new AttemptsConfiguration($idDocumentTextDataExtractionRetriesConfig);
         }
@@ -152,6 +162,7 @@ public function jsonSerialize(): \stdClass
             'error_url' => $this->getErrorUrl(),
             'privacy_policy_url' => $this->getPrivacyPolicyUrl(),
             'allow_handoff' => $this->getAllowHandoff(),
+            'enforce_handoff' => $this->getEnforceHandoff(),
             'attempts_configuration' => $this->getAttemptsConfiguration(),
             'biometric_consent_flow' => $this->getBiometricConsentFlow(),
             'dark_mode' => $this->getDarkMode(),
@@ -160,6 +171,22 @@ public function jsonSerialize(): \stdClass
         ]);
     }
 
+    /**
+     * Validates that enforce_handoff cannot be true when allow_handoff is false
+     *
+     * @param bool|null $allowHandoff
+     * @param bool|null $enforceHandoff
+     * @throws DocScanException
+     */
+    private function validateEnforceHandoff(?bool $allowHandoff, ?bool $enforceHandoff): void
+    {
+        if ($enforceHandoff === true && $allowHandoff === false) {
+            throw new DocScanException(
+                'enforce_handoff cannot be set to true when allow_handoff is false'
+            );
+        }
+    }
+
     /**
      * @return string|null
      */
@@ -240,6 +267,14 @@ public function getAllowHandoff(): ?bool
         return $this->allowHandoff;
     }
 
+    /**
+     * @return bool|null
+     */
+    public function getEnforceHandoff(): ?bool
+    {
+        return $this->enforceHandoff;
+    }
+
     /**
      * @return AttemptsConfiguration|null
      */

src/DocScan/Session/Create/SdkConfigBuilder.php

@@ -61,6 +61,11 @@ class SdkConfigBuilder
      */
     private $allowHandoff;
 
+    /**
+     * @var bool|null
+     */
+    private $enforceHandoff;
+
     /**
      * @var array<string,int>|null
      */
@@ -156,6 +161,20 @@ public function withAllowHandoff(bool $allowHandoff): self
         return $this;
     }
 
+    /**
+     * Sets whether handoff should be enforced during the session.
+     * Note: enforce_handoff cannot be set to true if allow_handoff is false.
+     * The validation will throw a DocScanException during build().
+     *
+     * @param bool $enforceHandoff Whether to enforce handoff
+     * @return $this
+     */
+    public function withEnforceHandoff(bool $enforceHandoff): self
+    {
+        $this->enforceHandoff = $enforceHandoff;
+        return $this;
+    }
+
     public function withBiometricConsentFlow(string $biometricConsentFlow): self
     {
         $this->biometricConsentFlow = $biometricConsentFlow;
@@ -264,6 +283,7 @@ public function build(): SdkConfig
             $this->errorUrl,
             $this->privacyPolicyUrl,
             $this->allowHandoff,
+            $this->enforceHandoff,
             $this->idDocumentTextDataExtractionRetriesConfig,
             $this->biometricConsentFlow,
             $this->darkMode,

tests/DocScan/Session/Create/SdkConfigBuilderTest.php

@@ -3,6 +3,7 @@
 namespace Yoti\Test\DocScan\Session\Create;
 
 use Yoti\DocScan\Constants;
+use Yoti\DocScan\Exception\DocScanException;
 use Yoti\DocScan\Session\Create\SdkConfigBuilder;
 use Yoti\Test\TestCase;
 
@@ -348,4 +349,133 @@ public function shouldSetCorrectValueWithDarkModeOff()
 
         $this->assertEquals('OFF', $result->getDarkMode());
     }
+
+    /**
+     * @test
+     * @covers ::withEnforceHandoff
+     * @covers \Yoti\DocScan\Session\Create\SdkConfig::getEnforceHandoff
+     */
+    public function shouldSetEnforceHandoffToTrue()
+    {
+        $result = (new SdkConfigBuilder())
+            ->withEnforceHandoff(true)
+            ->build();
+
+        $this->assertTrue($result->getEnforceHandoff());
+    }
+
+    /**
+     * @test
+     * @covers ::withEnforceHandoff
+     * @covers \Yoti\DocScan\Session\Create\SdkConfig::getEnforceHandoff
+     */
+    public function shouldSetEnforceHandoffToFalse()
+    {
+        $result = (new SdkConfigBuilder())
+            ->withEnforceHandoff(false)
+            ->build();
+
+        $this->assertFalse($result->getEnforceHandoff());
+    }
+
+    /**
+     * @test
+     * @covers \Yoti\DocScan\Session\Create\SdkConfigBuilder::build
+     * @covers \Yoti\DocScan\Session\Create\SdkConfig::getEnforceHandoff
+     */
+    public function enforceHandoffShouldBeNullWhenItIsNotSet()
+    {
+        $result = (new SdkConfigBuilder())
+            ->withAllowedCaptureMethod(self::SOME_CAPTURE_METHOD)
+            ->build();
+
+        $this->assertNull($result->getEnforceHandoff());
+    }
+
+    /**
+     * @test
+     * @covers ::withEnforceHandoff
+     * @covers ::withAllowHandoff
+     * @covers \Yoti\DocScan\Session\Create\SdkConfig::getEnforceHandoff
+     * @covers \Yoti\DocScan\Session\Create\SdkConfig::getAllowHandoff
+     */
+    public function shouldSetBothEnforceHandoffAndAllowHandoffToTrue()
+    {
+        $result = (new SdkConfigBuilder())
+            ->withAllowHandoff(true)
+            ->withEnforceHandoff(true)
+            ->build();
+
+        $this->assertTrue($result->getAllowHandoff());
+        $this->assertTrue($result->getEnforceHandoff());
+    }
+
+    /**
+     * @test
+     * @covers ::withEnforceHandoff
+     * @covers ::withAllowHandoff
+     * @covers \Yoti\DocScan\Session\Create\SdkConfig::__construct
+     */
+    public function shouldThrowExceptionWhenEnforceHandoffTrueAndAllowHandoffFalse()
+    {
+        $this->expectException(DocScanException::class);
+        $this->expectExceptionMessage('enforce_handoff cannot be set to true when allow_handoff is false');
+
+        (new SdkConfigBuilder())
+            ->withAllowHandoff(false)
+            ->withEnforceHandoff(true)
+            ->build();
+    }
+
+    /**
+     * @test
+     * @covers ::withEnforceHandoff
+     * @covers ::withAllowHandoff
+     * @covers \Yoti\DocScan\Session\Create\SdkConfig::getEnforceHandoff
+     * @covers \Yoti\DocScan\Session\Create\SdkConfig::getAllowHandoff
+     */
+    public function shouldAllowEnforceHandoffFalseWhenAllowHandoffFalse()
+    {
+        $result = (new SdkConfigBuilder())
+            ->withAllowHandoff(false)
+            ->withEnforceHandoff(false)
+            ->build();
+
+        $this->assertFalse($result->getAllowHandoff());
+        $this->assertFalse($result->getEnforceHandoff());
+    }
+
+    /**
+     * @test
+     * @covers ::withEnforceHandoff
+     * @covers \Yoti\DocScan\Session\Create\SdkConfig::getEnforceHandoff
+     */
+    public function shouldAllowEnforceHandoffTrueWhenAllowHandoffIsNull()
+    {
+        $result = (new SdkConfigBuilder())
+            ->withEnforceHandoff(true)
+            ->build();
+
+        $this->assertNull($result->getAllowHandoff());
+        $this->assertTrue($result->getEnforceHandoff());
+    }
+
+    /**
+     * @test
+     * @covers \Yoti\DocScan\Session\Create\SdkConfig::jsonSerialize
+     */
+    public function shouldIncludeEnforceHandoffInJsonSerialization()
+    {
+        $result = (new SdkConfigBuilder())
+            ->withAllowHandoff(true)
+            ->withEnforceHandoff(true)
+            ->build();
+
+        $expected = [
+            'allow_handoff' => true,
+            'enforce_handoff' => true
+        ];
+
+        $this->assertJsonStringEqualsJsonString(json_encode($expected), json_encode($result));
+    }
 }