Add invitation api

README.md

@@ -173,20 +173,20 @@ $promotion = Trustpilot::businessUnit()->promotion();
 
 ### Products
 ```php
-// Get all products
+// Get all products.
 $products = Trustpilot::products()->get();
 
-// Get the product with a sku of "samsung-galaxy-s10"
+// Get the product with a sku of "samsung-galaxy-s10".
 $product = Trustpilot::products()
     ->where('skus', 'samsung-galaxy-s10')
     ->first();
 
-// Get all products with a sku of "samsung-galaxy-s8", "samsung-galaxy-s9" or "samsung-galaxy-s10"
+// Get all products with a sku of "samsung-galaxy-s8", "samsung-galaxy-s9" or "samsung-galaxy-s10".
 $products = Trustpilot::products()
     ->where('skus', ['samsung-galaxy-s8', 'samsung-galaxy-s9', 'samsung-galaxy-s10'])
     ->get();
 
-// Updating a product
+// Updating a product.
 $product = Trustpilot::products()
     ->where('skus', 'samsung-galaxy-s10')
     ->first();
@@ -196,20 +196,82 @@ $product->currency = 'USD';
 $product->save();
 ```
 
+### Inivitations
+```php
+// Create a service invitation to John Doe from Business Name now.
+Trustpilot::businessUnit()->invitation()->service(
+    '#123456', 'John Doe', '[email protected]',
+    '[email protected]', 'Business Name'
+);
+
+// Create a service invitation to John Doe from Business Name now to be sent
+// in 5 days using a custom template id and to redirect to our website afterwards.
+Trustpilot::businessUnit()->invitation()->service(
+    '#123456', 'John Doe', '[email protected]',
+    '[email protected]', 'Business Name', '[email protected]',
+    \Carbon\Carbon::now()->addDays(5), '507f191e810c19729de860ea',
+    'https://example.com/',
+);
+
+// Create a product and service invitation from product skus.
+Trustpilot::businessUnit()->invitation()->products(
+    ['samsung-galaxy-s8', 'samsung-galaxy-s9', 'samsung-galaxy-s10'],
+    '#123456', 'John Doe', '[email protected]',
+    '[email protected]', 'Business Name'
+);
+
+// Create a product and service invitation from products.
+Trustpilot::businessUnit()->invitation()->products(
+    [
+        new Product([
+            'sku' => 'samsung-galaxy-s8',
+            'name' => 'Samsung Galaxy S8',
+            'brand' => 'Samsung Galaxy',
+            'productUrl' => 'https://example.com/products/samsung-galaxy-s8',
+            'imageUrl' => 'https://example.com/products/images/samsung-galaxy-s8.jpg',
+        ]),
+        new Product([
+            'sku' => 'samsung-galaxy-s10',
+            'name' => 'Samsung Galaxy S10',
+            'brand' => 'Samsung Galaxy',
+            'productUrl' => 'https://example.com/products/samsung-galaxy-s10',
+            'imageUrl' => 'https://example.com/products/images/samsung-galaxy-s10.jpg',
+        ]),
+    ],
+    '#123456', 'John Doe', '[email protected]',
+    '[email protected]', 'Business Name'
+);
+
+// Get a list of templates available to be used in invitations.
+$templates = Trustpilot::businessUnit()->invitation()->templates();
+
+// Generate a service review invitation link.
+$inviteUrl = Trustpilot::businessUnit()->invitation()->generateLink('#123456', 'John Doe', '[email protected]', 'https://example.com/');
+
+// Delete all invitation data related to the given e-mails.
+Trustpilot::businessUnit()->invitation()->deleteByEmails([
+    '[email protected]',
+    '[email protected]',
+]);
+
+// Delete all invitation data older than 5 years.
+Trustpilot::businessUnit()->invitation()->deleteBeforeDate(\Carbon\Carbon::now()->subYears(5));
+```
+
 ### Categories
 ```php
-// Get all categories
+// Get all categories.
 $categories = Trustpilot::categories()->get();
 
-// Get categories with a parent of "banking_money"
+// Get categories with a parent of "banking_money".
 $categories = Trustpilot::categories()
     ->where('parentId', 'banking_money')
     ->get();
 
-// Get category by id
+// Get category by id.
 $category = Trustpilot::categories()->find('trust_bank');
 
-// Get first three business units with the same category as your business unit
+// Get first three business units with the same category as your business unit.
 $businessUnits = Trustpilot::businessUnit()->categories()->first()->businessUnits()->limit(3)->get();
 ```
 

src/API/Api.php

@@ -82,6 +82,17 @@ public static function __callStatic($name, $arguments)
         return call_user_func_array([$instance, $name], $arguments);
     }
 
+    /**
+     * Set the endpoint of the api.
+     *
+     * @return self
+     */
+    protected function setEndpoint(string $endpoint): self
+    {
+        $this->endpoint = $endpoint;
+        return $this;
+    }
+
     /**
      * Set the path of the api.
      *

src/API/BusinessUnit/BusinessUnit.php

@@ -2,6 +2,7 @@
 namespace McCaulay\Trustpilot\API\BusinessUnit;
 
 use McCaulay\Trustpilot\API\BusinessUnit\Product\ProductApi;
+use McCaulay\Trustpilot\API\BusinessUnit\Review\Invitation\InvitationApi;
 use McCaulay\Trustpilot\API\Resource;
 use McCaulay\Trustpilot\Query\Builder;
 
@@ -42,7 +43,17 @@ public function reviews(): Builder
      */
     public function products(): ProductApi
     {
-        return new Product\ProductApi($this->id);
+        return new ProductApi($this->id);
+    }
+
+    /**
+     * Get the invitation api.
+     *
+     * @return \McCaulay\Trustpilot\API\BusinessUnit\Review\Invitation\InvitationApi
+     */
+    public function invitation(): InvitationApi
+    {
+        return new InvitationApi($this->id);
     }
 
     /**

src/API/BusinessUnit/Review/Invitation/InvitationApi.php

@@ -0,0 +1,216 @@
+<?php
+namespace McCaulay\Trustpilot\API\BusinessUnit\Review\Invitation;
+
+use Carbon\Carbon;
+use DateTime;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Collection;
+use McCaulay\Trustpilot\Api;
+use McCaulay\Trustpilot\API\BusinessUnit\Review\Invitation\Template;
+use McCaulay\Trustpilot\API\BusinessUnit\Review\Review;
+
+class InvitationApi extends Api
+{
+    /**
+     * The business unit id.
+     *
+     * @var int
+     */
+    public $businessUnitId = null;
+
+    /**
+     * Initialise the business unit reviews with an optional business unit id.
+     * If no business unit id is given, it uses the business unit from the config.
+     *
+     * @param null|string $businessUnitId
+     */
+    public function __construct(?string $businessUnitId = null)
+    {
+        parent::__construct();
+        $this->businessUnitId = $businessUnitId ?? config('trustpilot.unit_id');
+        $this->setPath('/private/business-units/' . $this->businessUnitId);
+        $this->setEndpoint(config('trustpilot.endpoints.invitation'));
+    }
+
+    /**
+     * Create the product review invite.
+     *
+     * @param array $products An array of product skus, or products
+     * @param string $referenceId
+     * @param string $customerName
+     * @param string $customerEmail
+     * @param string $replyTo
+     * @param string $senderName
+     * @param string $senderEmail
+     * @param null|\DateTime $sendProductAt When to send the product review invite at. Note this must be after the send at.
+     * @param null|\DateTime $sendAt When to send the service review invite at.
+     * @param null|string $templateId
+     * @param null|string $redirectUrl
+     * @param array $tags
+     * @param string $locale
+     * @param null|string $locationId
+     * @return void
+     */
+    public function products(array $products, string $referenceId,
+        string $customerName, string $customerEmail, string $replyTo,
+        string $senderName,
+        ?string $senderEmail = null,
+        ?DateTime $sendProductAt = null,
+        ?DateTime $sendAt = null, ?string $templateId = null,
+        ?string $redirectUrl = null, array $tags = [], string $locale = 'en-GB',
+        ?string $locationId = null
+    ): void {
+        // Default send product at
+        if ($sendProductAt == null) {
+            $sendProductAt = $sendAt == null ? Carbon::now()->subDay() : $sendAt->copy()->addDay();
+        }
+
+        // Setup product review invitation array
+        $productReviewInvitation = array_filter([
+            'preferredSendTime' => $sendProductAt->format('Y-m-d\TH:i:s'),
+            'redirectUri' => $redirectUrl,
+            'templateId' => $templateId,
+        ]);
+
+        // Append products or product skus
+        $productKey = 'productSkus';
+        if (count($products) > 0) {
+            if (Arr::isAssoc($products) || !is_string($products[0])) {
+                $productKey = 'products';
+                $products = collect($products)->map(function ($product) {
+                    if (is_array($product)) {
+                        return $product;
+                    }
+                    return $product->toArray();
+                })->toArray();
+            }
+        }
+        $productReviewInvitation[$productKey] = $products;
+
+        $this->service(
+            $referenceId, $customerName, $customerEmail, $replyTo, $senderName,
+            $senderEmail, $sendAt, $templateId, $redirectUrl, $tags,
+            $locale, $locationId, $productReviewInvitation
+        );
+    }
+
+    /**
+     * Create the service review invite.
+     *
+     * @param string $referenceId
+     * @param string $customerName
+     * @param string $customerEmail
+     * @param string $replyTo
+     * @param string $senderName
+     * @param string $senderEmail
+     * @param null|\DateTime $sendAt When to send the service review invite at.
+     * @param null|string $templateId
+     * @param null|string $redirectUrl
+     * @param array $tags
+     * @param string $locale
+     * @param null|string $locationId
+     * @param array $productReviewInvitation
+     * @return void
+     */
+    public function service(string $referenceId, string $customerName,
+        string $customerEmail, string $replyTo, string $senderName,
+        ?string $senderEmail = null,
+        ?DateTime $sendAt = null, ?string $templateId = null,
+        ?string $redirectUrl = null, array $tags = [], string $locale = 'en-GB',
+        ?string $locationId = null, array $productReviewInvitation = []
+    ): void {
+        // Default send at
+        if ($sendAt == null) {
+            $sendAt = Carbon::now()->subDays(2);
+        }
+
+        // Default sender email
+        if ($senderEmail == null) {
+            $senderEmail = '[email protected]';
+        }
+
+        $this->post('/email-invitations', [], array_filter([
+            'referenceNumber' => $referenceId,
+            'consumerName' => $customerName,
+            'consumerEmail' => $customerEmail,
+            'senderName' => $senderName,
+            'senderEmail' => $senderEmail,
+            'replyTo' => $replyTo,
+            'locale' => $locale,
+            'locationId' => $locationId,
+            'serviceReviewInvitation' => array_filter([
+                'preferredSendTime' => $sendAt->format('Y-m-d\TH:i:s'),
+                'redirectUri' => $redirectUrl,
+                'tags' => $tags,
+                'templateId' => $templateId,
+            ]),
+            'productReviewInvitation' => $productReviewInvitation,
+        ]), true);
+    }
+
+    /**
+     * Generate a review invitation link.
+     *
+     * @param string $referenceId
+     * @param string $name
+     * @param string $email
+     * @param null|string $redirectUrl
+     * @param array $tags
+     * @param string $locale
+     * @param null|string $locationId
+     * @return string
+     */
+    public function generateLink(string $referenceId, string $name,
+        string $email, ?string $redirectUrl = null, array $tags = [],
+        string $locale = 'en-GB', ?string $locationId = null
+    ): string {
+        return $this->post('/invitation-links', [], array_filter([
+            'referenceId' => $referenceId,
+            'name' => $name,
+            'email' => $email,
+            'redirectUri' => $redirectUrl,
+            'tags' => $tags,
+            'locale' => $locale,
+            'locationId' => $locationId,
+        ]), true)->url;
+    }
+
+    /**
+     * Delete all information data related to the e-mails.
+     *
+     * @param array $emails
+     * @return void
+     */
+    public function deleteByEmails(array $emails): void
+    {
+        $this->post('/invitation-data/delete', [], [
+            'customerEmails' => $emails,
+        ], true);
+    }
+
+    /**
+     * Delete all information data before the given date.
+     *
+     * @param \DateTime $date
+     * @return void
+     */
+    public function deleteBeforeDate(DateTime $date): void
+    {
+        $this->post('/invitation-data/delete', [], [
+            'deleteOlderThan' => $date->format('Y-m-d\TH:i:s'),
+        ], true);
+    }
+
+    /**
+     * Get a list of invitation templates.
+     *
+     * @return \Illuminate\Support\Collection
+     */
+    public function templates(): Collection
+    {
+        $response = $this->get('/templates', [], true);
+        return collect($response->templates)->map(function ($template) {
+            return (new Template())->data($template);
+        });
+    }
+}

src/API/BusinessUnit/Review/Invitation/Template.php

@@ -0,0 +1,9 @@
+<?php
+namespace McCaulay\Trustpilot\API\BusinessUnit\Review\Invitation;
+
+use McCaulay\Trustpilot\API\Resource;
+
+class Template extends Resource
+{
+    //
+}