Feature/messages v1 ga (#319)

* Skeleton messages architecture, need to implement more interface methods

* More scaffolding

* More scaffolding, first test passing

* MMS implementation, message objects

* WhatsApp basic structure for testing

* WhatsApp extended implementation

* Messenger implementation

* Viber implementation

* Fix failing test due to a find and replace mistake

* ViberService trait for image

* Docs update in readme

* Update Readme to include Messages API

* Add the messages client into the core mapper

* Change API URL, set errors on 200 to false

* Refactor to reuse common outputs

* Refactor to adhere to some DRY, added custom error handler for API responses plus tests

* Take out needless links from readme

* Fix collection names

* Quick confiig move for base url

* Channel namespace change

* Update README.md

Co-authored-by: Chris Tankersley <chris@ctankersley.com>

* Update README.md

Co-authored-by: Chris Tankersley <chris@ctankersley.com>

Co-authored-by: Chris Tankersley <chris@ctankersley.com>

Author: SecondeJK

README.md

@@ -73,7 +73,7 @@ For APIs that would usually hit `rest.nexmo.com`, supplying a `base_rest_url` as
 Examples
 --------
 
-### Sending a Message
+### Sending a Message via the SMS API
 
 To use [Vonage's SMS API][doc_sms] to send an SMS message, call the `$client->sms()->send()` method.
 
@@ -164,6 +164,71 @@ $isValid = $signature->check($_GET['sig']);
 
 Using your signature secret and the other supplied parameters, the signature can be calculated and checked against the incoming signature value.
 
+### Sending a Message via. the Messages API
+
+The [Messages API](https://developer.vonage.com/api/messages-olympus) is used to send a variety of outbound messages. 
+The following platforms are currently supported:
+* **SMS**
+* **MMS**
+* **WhatsApp**
+* **Messenger**
+* **Viber**
+
+Each one of these platforms has a different category of message you can send (for example, with WhatsApp you can send
+text, an image, audio, video, a file or a template but for Viber you can only send a text or an image). You can find
+all the sendable message types under the namespace `\Vonage\Messages\Channel`. The reason each type is separated
+out this way is that the platform and message type requires different parameters in the API call.
+
+The `\Vonage\Messages\Client` is configured in a similar way to the SMS API Client. The difference is that the
+authentication can be either a JSON Web Token (JWT) or Basic Authentication. You can find more info on how to set
+up your Client's credentials under the 'Usage' section of this ReadMe.
+
+Here some examples:
+
+### Sending a WhatsApp Text
+
+First, we need to create a new WhatsAppText object like so:
+
+```php
+$whatsAppText = new Vonage\Messages\Channel\WhatsApp\WhatsAppText(
+    FROM_NUMBER,
+    TO_NUMBER,
+    'this is a WA text from vonage'
+);
+```
+
+The Messages API Client has one method, `send()` where you can send any of the message types provided. So, to send this
+message, the following code will do that, assuming you have already set up your Vonage client correctly:
+
+```php
+$client->messages()->send($whatsAppText);
+```
+
+Your response will be a JSON payload if the error range is with 200, or will throw a relevant `APIException` if it's
+within 400/500.
+
+### Send a Viber Image
+
+Some `Channel` objects require more arguments in order to be created. You can see the rough mapping of these
+requirements by comparing the constructor arguments vs. the API Documentation. Some of these messages take custom
+reusable objects (that are under the `\Vonage\Messages\MessageObjects` namespace). One of these is an image - so
+here is an example of how to send a Viber Image:
+
+```php
+$imageObject = Vonage\Messages\MessageObjects\ImageObject(
+    'https://picsum.photos/200/300',
+    'image caption'
+);
+
+$viberImage = new Vonage\Messages\Channel\Viber\ViberImage(
+    FROM_NUMBER,
+    TO_NUMBER,
+    $imageObject
+);
+
+$client->messages()->send($viberImage);
+```
+
 ### 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,
@@ -743,7 +808,7 @@ Check out the [documentation](https://developer.nexmo.com/number-insight/code-sn
 | Dispatch API | Beta |❌|
 | External Accounts API | Beta |❌|
 | Media API | Beta | ❌|
-| Messages API | Beta |❌|
+| Messages API | General Availability |✅|
 | Number Insight API | General Availability |✅|
 | Number Management API | General Availability |✅|
 | Pricing API | General Availability |✅|

src/Client.php

@@ -52,6 +52,7 @@
 use Vonage\Redact\ClientFactory as RedactClientFactory;
 use Vonage\Secrets\ClientFactory as SecretsClientFactory;
 use Vonage\SMS\ClientFactory as SMSClientFactory;
+use Vonage\Messages\ClientFactory as MessagesClientFactory;
 use Vonage\Verify\ClientFactory as VerifyClientFactory;
 use Vonage\Verify\Verification;
 use Vonage\Voice\ClientFactory as VoiceClientFactory;
@@ -76,6 +77,7 @@
  *
  * @method Account\Client account()
  * @method Message\Client message()
+ * @method Messages\Client messages()
  * @method Application\Client applications()
  * @method Conversion\Client conversion()
  * @method Insights\Client insights()
@@ -205,6 +207,7 @@ public function __construct(CredentialsInterface $credentials, $options = [], ?C
                     'conversion' => ConversionClientFactory::class,
                     'insights' => InsightsClientFactory::class,
                     'numbers' => NumbersClientFactory::class,
+                    'messages' => MessagesClientFactory::class,
                     'redact' => RedactClientFactory::class,
                     'secrets' => SecretsClientFactory::class,
                     'sms' => SMSClientFactory::class,
@@ -587,7 +590,10 @@ protected static function requiresAuthInUrlNotBody(RequestInterface $request): b
     {
         $path = $request->getUri()->getPath();
 
-        return strpos($path, '/v1/redact') === 0;
+        $isRedact =  strpos($path, '/v1/redact') === 0;
+        $isMessages =  strpos($path, '/v1/messages') === 0;
+
+        return $isRedact || $isMessages;
     }
 
     protected function needsKeypairAuthentication(RequestInterface $request): bool

src/Messages/Channel/BaseMessage.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace Vonage\Messages\Channel;
+
+abstract class BaseMessage implements Message
+{
+    protected string $subType;
+    protected string $to;
+    protected string $from;
+    protected string $channel;
+    protected ?string $clientRef = null;
+
+    public const MESSAGES_SUBTYPE_TEXT = 'text';
+    public const MESSAGES_SUBTYPE_IMAGE = 'image';
+    public const MESSAGES_SUBTYPE_VCARD = 'vcard';
+    public const MESSAGES_SUBTYPE_AUDIO = 'audio';
+    public const MESSAGES_SUBTYPE_VIDEO = 'video';
+    public const MESSAGES_SUBTYPE_FILE = 'file';
+    public const MESSAGES_SUBTYPE_TEMPLATE = 'template';
+    public const MESSAGES_SUBTYPE_CUSTOM = 'custom';
+
+    public function getClientRef(): ?string
+    {
+        return $this->clientRef;
+    }
+
+    public function setClientRef(string $clientRef): void
+    {
+        $this->clientRef = $clientRef;
+    }
+
+    public function getSubType(): string
+    {
+        return $this->subType;
+    }
+
+    public function getFrom(): string
+    {
+        return $this->from;
+    }
+
+    public function setFrom(string $from): void
+    {
+        $this->from = $from;
+    }
+
+    public function getChannel(): string
+    {
+        return $this->channel;
+    }
+
+    public function getTo(): string
+    {
+        return $this->to;
+    }
+
+    public function setTo(string $to): void
+    {
+        $this->to = $to;
+    }
+
+    public function getBaseMessageUniversalOutputArray(): array
+    {
+        $returnArray = [
+            'message_type' => $this->getSubType(),
+            'to' => $this->getTo(),
+            'from' => $this->getFrom(),
+            'channel' => $this->getChannel(),
+        ];
+
+        if ($this->getClientRef()) {
+            $returnArray['client_ref'] = $this->getClientRef();
+        }
+
+        return $returnArray;
+    }
+}

src/Messages/Channel/MMS/MMSAudio.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Vonage\Messages\Channel\MMS;
+
+use Vonage\Messages\MessageObjects\AudioObject;
+use Vonage\Messages\Channel\BaseMessage;
+
+class MMSAudio extends BaseMessage
+{
+    protected string $channel = 'mms';
+    protected string $subType = BaseMessage::MESSAGES_SUBTYPE_AUDIO;
+    protected AudioObject $audioObject;
+
+    public function __construct(
+        string $to,
+        string $from,
+        AudioObject $audioObject
+    ) {
+        $this->to = $to;
+        $this->from = $from;
+        $this->audioObject = $audioObject;
+    }
+
+    public function toArray(): array
+    {
+        $returnArray = $this->getBaseMessageUniversalOutputArray();
+        $returnArray['audio'] = $this->audioObject->toArray();
+
+        return $returnArray;
+    }
+}

src/Messages/Channel/MMS/MMSImage.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Vonage\Messages\Channel\MMS;
+
+use Vonage\Messages\MessageObjects\ImageObject;
+use Vonage\Messages\Channel\BaseMessage;
+
+class MMSImage extends BaseMessage
+{
+    protected string $channel = 'mms';
+    protected string $subType = BaseMessage::MESSAGES_SUBTYPE_IMAGE;
+    protected ImageObject $image;
+
+    public function __construct(
+        string $to,
+        string $from,
+        ImageObject $image
+    ) {
+        $this->to = $to;
+        $this->from = $from;
+        $this->image = $image;
+    }
+
+    public function toArray(): array
+    {
+        $returnArray = $this->getBaseMessageUniversalOutputArray();
+        $returnArray['image'] = $this->image->toArray();
+
+        return $returnArray;
+    }
+}

src/Messages/Channel/MMS/MMSVideo.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Vonage\Messages\Channel\MMS;
+
+use Vonage\Messages\MessageObjects\AudioObject;
+use Vonage\Messages\MessageObjects\VideoObject;
+use Vonage\Messages\Channel\BaseMessage;
+
+class MMSVideo extends BaseMessage
+{
+    protected string $channel = 'mms';
+    protected string $subType = BaseMessage::MESSAGES_SUBTYPE_VIDEO;
+    protected VideoObject $videoObject;
+
+    public function __construct(
+        string $to,
+        string $from,
+        VideoObject $videoObject
+    ) {
+        $this->to = $to;
+        $this->from = $from;
+        $this->videoObject = $videoObject;
+    }
+
+    public function toArray(): array
+    {
+        $returnArray = $this->getBaseMessageUniversalOutputArray();
+        $returnArray['video'] = $this->videoObject->toArray();
+
+        return $returnArray;
+    }
+}

src/Messages/Channel/MMS/MMSvCard.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Vonage\Messages\Channel\MMS;
+
+use Vonage\Messages\MessageObjects\VCardObject;
+use Vonage\Messages\Channel\BaseMessage;
+
+class MMSvCard extends BaseMessage
+{
+    protected string $channel = 'mms';
+    protected string $subType = BaseMessage::MESSAGES_SUBTYPE_VCARD;
+    protected VCardObject $vCard;
+
+    public function __construct(
+        string $to,
+        string $from,
+        VCardObject $vCard
+    ) {
+        $this->to = $to;
+        $this->from = $from;
+        $this->vCard = $vCard;
+    }
+
+    public function toArray(): array
+    {
+        $returnArray = $this->getBaseMessageUniversalOutputArray();
+        $returnArray['vcard'] = $this->vCard->toArray();
+
+        return $returnArray;
+    }
+}

src/Messages/Channel/Message.php

@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * Vonage Client Library for PHP
+ *
+ * @copyright Copyright (c) 2016-2020 Vonage, Inc. (http://vonage.com)
+ * @license https://github.com/Vonage/vonage-php-sdk-core/blob/master/LICENSE.txt Apache License 2.0
+ */
+
+declare(strict_types=1);
+
+namespace Vonage\Messages\Channel;
+
+interface Message
+{
+    public function toArray(): array;
+    public function getTo(): string;
+    public function setTo(string $to): void;
+    public function getFrom(): string;
+    public function setFrom(string $from): void;
+    public function getClientRef(): ?string;
+    public function getChannel(): string;
+    public function getSubType(): string;
+    public function setClientRef(string $clientRef): void;
+
+    /**
+     * All message types have shared outputs required by the endpoint.
+     * Child classes are required to call this before assembling their
+     * own specific output
+     *
+     * @return array
+     */
+    public function getBaseMessageUniversalOutputArray(): array;
+}

src/Messages/Channel/Messenger/InvalidCategoryException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace Vonage\Messages\Channel\Messenger;
+
+class InvalidCategoryException extends \Exception
+{
+}