Verify v2 (#389)

* failing client boot skeleton

* Scaffolding

* SMS sending and validation

* Complete happy path tests for requests

* Webhook testing, error handling

* Get factory to generate verify 2 client

* Fix CRLF discrepancies over environments

* Let's try CRLF again

* Docs and constant use for readability

* Webhooks reimagined, docs

Author: SecondeJK

.gitattributes

@@ -13,3 +13,4 @@
 # Ignore all differences in line endings for requests
 /test/SMS/requests/* text eol=crlf
 /test/Voice/requests/* text eol=crlf
+/test/Verify2/Fixtures/Requests/* text eol=crlf

README.md

@@ -228,6 +228,8 @@ $viberImage = new Vonage\Messages\Channel\Viber\ViberImage(
 $client->messages()->send($viberImage);
 ```
 
+## Verify Examples (v1)
+
 ### Starting a Verification
 
 Vonage's [Verify API][doc_verify] makes it easy to prove that a user has provided their own phone number during signup,
@@ -295,6 +297,93 @@ echo "Started verification with an id of: " . $response['request_id'];
 
 Once the user inputs the pin code they received, call the `/check` endpoint with the request ID and the pin to confirm the pin is correct.
 
+## Verify Examples (v2)
+
+### Starting a Verification
+
+Vonage's Verify v2 relies more on asynchronous workflows via. webhooks, and more customisable Verification
+workflows to the developer. To start a verification, you'll need the API client, which is under the namespace
+`verify2`.
+
+Making a Verify request needs a 'base' channel of communication to deliver the mode of verification. You can
+customise these interactions by adding different 'workflows'. For each type of workflow, there is a Verify2 class
+you can create that will handle the initial workflow for you. For example:
+
+```php
+$client = new Vonage\Client(
+    new Vonage\Client\Credentials\Basic(API_KEY, API_SECRET),
+);
+
+$smsRequest = new \Vonage\Verify2\Request\SMSRequest('TO_NUMBER');
+$client->verify2()->startVerification($smsRequest);
+```
+
+The `SMSRequest` object will resolve defaults for you, and will create a default `workflow` object to use SMS.
+You can, however, add multiple workflows that operate with fall-back logic. For example, if you wanted to create
+a Verification that tries to get a PIN code off the user via. SMS, but in case there is a problem with SMS delivery
+you wish to add a Voice fallback: you can add it.
+
+```php
+$client = new Vonage\Client(
+    new Vonage\Client\Credentials\Basic(API_KEY, API_SECRET),
+);
+
+$smsRequest = new \Vonage\Verify2\Request\SMSRequest('TO_NUMBER', 'my-verification');
+$voiceWorkflow = new \Vonage\Verify2\VerifyObjects\VerificationWorkflow(\Vonage\Verify2\VerifyObjects\VerificationWorkflow::WORKFLOW_VOICE, 'TO_NUMBER');
+$smsRequest->addWorkflow($voiceWorkflow);
+$client->verify2()->startVerification($smsRequest);
+```
+This adds the voice workflow to the original SMS request. The verification request will try and resolve the process in
+the order that it is given (starting with the default for the type of request).
+
+The base request types are as follows:
+
+* `SMSRequest`
+* `WhatsAppRequest`
+* `WhatsAppInterativeRequest`
+* `EmailRequest`
+* `VoiceRequest`
+* `SilentAuthRequest`
+
+For adding workflows, you can see the available valid workflows as constants within the `VerificationWorkflow` object.
+For a better developer experience, you can't create an invalid workflow due to the validation that happens on the object.
+
+### Check a submitted code
+
+To submit a code, you'll need to surround the method in a try/catch due to the nature of the API. If the code is correct,
+the method will return a `true` boolean. If it fails, it will throw the relevant Exception from the API that will need to
+be caught.
+
+```php
+$code = '1234';
+try {
+    $client->verify2()->check($code);
+} catch (\Exception $e) {
+    var_dump($e->getMessage())
+}
+```
+
+### Webhooks
+
+As events happen during a verification workflow, events and updates will fired as webhooks. Incoming server requests that conform to
+PSR-7 standards can be hydrated into a webhook value object for nicer interactions. You can also hydrate
+them from a raw array. If successful, you will receive a value object back for the type of event/update. Possible webhooks are:
+
+* `VerifyEvent`
+* `VerifyStatusUpdate`
+* `VerifySilentAuthUpdate`
+
+```php
+// From a request object
+$verificationEvent = \Vonage\Verify2\Webhook\Factory::createFromRequest($request);
+var_dump($verificationEvent->getStatus());
+// From an array
+$payload = $request->getBody()->getContents()
+$verificationEvent = \Vonage\Verify2\Webhook\Factory::createFromArray($payload);
+var_dump($verificationEvent->getStatus());
+```
+
+
 ### Making a Call 
 
 All `$client->voice()` methods require the client to be constructed with a `Vonage\Client\Credentials\Keypair`, or a 
@@ -797,25 +886,26 @@ Check out the [documentation](https://developer.nexmo.com/number-insight/code-sn
 
 ## Supported APIs
 
-| API   | API Release Status |  Supported?
-|----------|:---------:|:-------------:|
-| Account API | General Availability |✅|
-| Alerts API | General Availability |✅|
-| Application API | General Availability |✅|
-| Audit API | Beta |❌|
-| Conversation API | Beta |❌|
-| Dispatch API | Beta |❌|
-| External Accounts API | Beta |❌|
-| Media API | Beta | ❌|
-| Messages API | General Availability |✅|
-| Number Insight API | General Availability |✅|
-| Number Management API | General Availability |✅|
-| Pricing API | General Availability |✅|
-| Redact API | General Availability |✅|
-| Reports API | Beta |❌|
-| SMS API | General Availability |✅|
-| Verify API | General Availability |✅|
-| Voice API | General Availability |✅|
+| API                    |  API Release Status  |  Supported?
+|------------------------|:--------------------:|:-------------:|
+| Account API            | General Availability |✅|
+| Alerts API             | General Availability |✅|
+| Application API        | General Availability |✅|
+| Audit API              |         Beta         |❌|
+| Conversation API       |         Beta         |❌|
+| Dispatch API           |         Beta         |❌|
+| External Accounts API  |         Beta         |❌|
+| Media API              |         Beta         | ❌|
+| Messages API           | General Availability |✅|
+| Number Insight API     | General Availability |✅|
+| Number Management API  | General Availability |✅|
+| Pricing API            | General Availability |✅|
+| Redact API             | General Availability |✅|
+| Reports API            |         Beta         |❌|
+| SMS API                | General Availability |✅|
+| Verify API             | General Availability |✅|
+| Verify API (Version 2) |         Beta         |❌|
+| Voice API              | General Availability |✅|
 
 ## Troubleshooting
 

phpunit.xml.dist

@@ -20,6 +20,9 @@
     <testsuite name="default">
       <directory>test</directory>
     </testsuite>
+    <testsuite name="verify2">
+      <directory>test/Verify2</directory>
+    </testsuite>
   </testsuites>
   <php>
         <ini name='error_reporting' value='E_ALL' />

src/Client.php

@@ -52,6 +52,7 @@
 use Vonage\SMS\ClientFactory as SMSClientFactory;
 use Vonage\Messages\ClientFactory as MessagesClientFactory;
 use Vonage\Verify\ClientFactory as VerifyClientFactory;
+use Vonage\Verify2\ClientFactory as Verify2ClientFactory;
 use Vonage\Verify\Verification;
 use Vonage\Voice\ClientFactory as VoiceClientFactory;
 use Vonage\Logger\{LoggerAwareInterface, LoggerTrait};
@@ -81,6 +82,7 @@
  * @method Secrets\Client secrets()
  * @method SMS\Client sms()
  * @method Verify\Client  verify()
+ * @method Verify2\Client  verify2()
  * @method Voice\Client voice()
  *
  * @property string restUrl
@@ -217,6 +219,7 @@ public function __construct(
                     'secrets' => SecretsClientFactory::class,
                     'sms' => SMSClientFactory::class,
                     'verify' => VerifyClientFactory::class,
+                    'verify2' => Verify2ClientFactory::class,
                     'voice' => VoiceClientFactory::class,
 
                     // Additional utility classes

src/Verify2/Client.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace Vonage\Verify2;
+
+use Laminas\Diactoros\Request;
+use Vonage\Client\APIClient;
+use Vonage\Client\APIResource;
+use Vonage\Client\Exception\Exception;
+use Vonage\Verify2\Request\BaseVerifyRequest;
+
+class Client implements APIClient
+{
+    public function __construct(protected APIResource $api)
+    {
+    }
+
+    public function getAPIResource(): APIResource
+    {
+        return $this->api;
+    }
+
+    public function startVerification(BaseVerifyRequest $request): ?array
+    {
+        return $this->getAPIResource()->create($request->toArray());
+    }
+
+    public function check(string $requestId, $code): bool
+    {
+        try {
+            $response = $this->getAPIResource()->create(['code' => $code], $requestId);
+        } catch (Exception $e) {
+            // For horrible reasons in the API Error Handler, throw the error unless it's a 409.
+            if ($e->getCode() === 409) {
+                throw new \Vonage\Client\Exception\Request('Conflict: The current Verify workflow step does not support a code.');
+            }
+
+            throw $e;
+        }
+
+        return true;
+    }
+}

src/Verify2/ClientFactory.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Vonage\Verify2;
+
+use Vonage\Client\APIResource;
+use Vonage\Client\Credentials\Handler\BasicHandler;
+use Vonage\Client\Credentials\Handler\KeypairHandler;
+
+class ClientFactory
+{
+    public function __invoke(): Client
+    {
+        $api = $container->make(APIResource::class);
+        $api->setIsHAL(false)
+            ->setErrorsOn200(false)
+            ->setClient($this->vonageClient->reveal())
+            ->setAuthHandler([new BasicHandler(), new KeypairHandler()])
+            ->setBaseUrl('https://api.nexmo.com/v2/verify/');
+
+        return new Client($api);
+    }
+}

src/Verify2/Request/BaseVerifyRequest.php

@@ -0,0 +1,137 @@
+<?php
+
+namespace Vonage\Verify2\Request;
+
+use Vonage\Verify2\VerifyObjects\VerificationLocale;
+use Vonage\Verify2\VerifyObjects\VerificationWorkflow;
+
+abstract class BaseVerifyRequest implements RequestInterface
+{
+    private const TIMEOUT_MIN = 60;
+    private const TIMEOUT_MAX = 900;
+    private const LENGTH_MIN = 4;
+    private const LENGTH_MAX = 10;
+
+    protected ?VerificationLocale $locale = null;
+
+    protected int $timeout = 300;
+
+    protected ?string $clientRef = null;
+
+    protected int $length = 4;
+
+    protected string $brand;
+
+    protected array $workflows = [];
+
+    public function getLocale(): ?VerificationLocale
+    {
+        return $this->locale;
+    }
+
+    public function setLocale(?VerificationLocale $verificationLocale): static
+    {
+        $this->locale = $verificationLocale;
+    }
+
+    public function getTimeout(): int
+    {
+        return $this->timeout;
+    }
+
+    public function setTimeout(int $timeout): static
+    {
+        $range = [
+            'options' => [
+                'min_range' => self::TIMEOUT_MIN,
+                'max_range' => self::TIMEOUT_MAX
+                ]
+        ];
+
+        if (!filter_var($timeout, FILTER_VALIDATE_INT, $range)) {
+            throw new \OutOfBoundsException('Timeout ' . $timeout . ' is not valid');
+        }
+
+        $this->timeout = $timeout;
+
+        return $this;
+    }
+
+    public function getClientRef(): ?string
+    {
+        return $this->clientRef;
+    }
+
+    public function setClientRef(?string $clientRef): static
+    {
+        $this->clientRef = $clientRef;
+
+        return $this;
+    }
+
+    public function getLength(): int
+    {
+        return $this->length;
+    }
+
+    public function setLength(int $length): static
+    {
+        $range = [
+            'options' => [
+                'min_range' => self::LENGTH_MIN,
+                'max_range' => self::LENGTH_MAX
+            ]
+        ];
+
+        if (!filter_var($length, FILTER_VALIDATE_INT, $range)) {
+            throw new \OutOfBoundsException('PIN Length ' . $length . ' is not valid');
+        }
+
+        $this->length = $length;
+
+        return $this;
+    }
+
+    public function getBrand(): string
+    {
+        return $this->brand;
+    }
+
+    public function setBrand(string $brand): static
+    {
+        $this->brand = $brand;
+
+        return $this;
+    }
+
+    public function getWorkflows(): array
+    {
+        return array_map(static function($workflow) {
+            return $workflow->toArray();
+        }, $this->workflows);
+    }
+
+    public function addWorkflow(VerificationWorkflow $verificationWorkflow): static
+    {
+        $this->workflows[] = $verificationWorkflow;
+
+        return $this;
+    }
+
+    public function getBaseVerifyUniversalOutputArray(): array
+    {
+        $returnArray = [
+            'locale' => $this->getLocale()->getCode(),
+            'channel_timeout' => $this->getTimeout(),
+            'code_length' => $this->getLength(),
+            'brand' => $this->getBrand(),
+            'workflow' => $this->getWorkflows()
+        ];
+
+        if ($this->getClientRef()) {
+            $returnArray['client_ref'] = $this->getClientRef();
+        }
+
+        return $returnArray;
+    }
+}