New endpoints for eshops orders (#9)

* Extends api for orders eshops

* Setters in model

* FIx order item property

* Fixes

* Refactor - Abstract orders

* Refactor readme and remove unused orders abstract constructor

* Import 'SmartEmailing\v3\Api' is never used

* Return types Api

* Fix status order canceled

Co-authored-by: Lukas Skywalker <[email protected]>

readme.md

@@ -95,6 +95,7 @@ try {
 * [x] [Emails](https://app.smartemailing.cz/docs/api/v3/index.html#api-Emails)
 * [x] [Newsletter](https://app.smartemailing.cz/docs/api/v3/index.html#api-Newsletter)
 * [ ] [Webhooks](https://app.smartemailing.cz/docs/api/v3/index.html#api-Webhooks)
+* [x] [E shops](https://app.smartemailing.cz/docs/api/v3/index.html#api-E_shops) Notifies SmartEmailing about new order in e-shop.
 
 ## Advanced docs
 
@@ -254,7 +255,6 @@ if ($customField = $api->customFields()->exists('name')) {
     throw new Exception('Not found!', 404);
 }
 ```
-
 ### Send / Transactional emails
 The implementation of API call ``send/transactional-emails-bulk``: https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_transactional_emails
 ## Full transactional email example
@@ -363,9 +363,39 @@ $transactionEmail->addTask($task);
 $transactionEmail->send();
 ```
 
+
+## E_shops - Add Placed order
+
+The E_shops section have two endpoints to set single Order or import orders in bulk.
+
+Example add single order
+```php
+use \SmartEmailing\v3\Request\Eshops\Model\Order;
+use \SmartEmailing\v3\Request\Eshops\Model\OrderItem;
+use \SmartEmailing\v3\Request\Eshops\Model\Price;
+
+$order = new Order('my-eshop', 'ORDER0001', '[email protected]');
+$order->orderItems()->add(
+    new OrderItem(
+        'ABC123',   // item Id
+        'My Product', // item name
+        10,          // quantity
+        new Price(
+            100, // without vat
+            121, // with vat
+            'CZK' // currency code
+        ),
+        'https://myeshop.cz/product/ABC123'  // product url
+    )
+);
+$api->eshopOrders()->addOrder($order)->send();
+```
+
 ### Send / Bulk custom sms
 The implementation of API call ``send/custom-sms-bulk``: https://app.smartemailing.cz/docs/api/v3/index.html#api-Custom_campaigns-Send_bulk_custom_SMS
+
 ## Full send sms example
+
 ```php
 $bulkCustomSms = new BulkCustomSms($api);
 
@@ -402,4 +432,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute changes. All contri
 was written by [Martin Kluska](http://kluska.cz) and is released under the
 [MIT License](LICENSE.md).
 
-Copyright (c) 2016 Martin Kluska
+Copyright (c) 2016 - 2022 Martin Kluska and contributors

src/Api.php

@@ -1,12 +1,14 @@
 <?php
+
 namespace SmartEmailing\v3;
 
 use GuzzleHttp\Client;
 use SmartEmailing\v3\Request\Contactlists\ContactlistEndpoint;
-use SmartEmailing\v3\Request\Contactlists\Contactlists;
 use SmartEmailing\v3\Request\Credentials\Credentials;
 use SmartEmailing\v3\Request\CustomFields\CustomFields;
 use SmartEmailing\v3\Request\Email\EmailsEndpoint;
+use SmartEmailing\v3\Request\Eshops\EshopOrders;
+use SmartEmailing\v3\Request\Eshops\EshopOrdersBulk;
 use SmartEmailing\v3\Request\Import\Import;
 use SmartEmailing\v3\Request\Newsletter\Newsletter;
 use SmartEmailing\v3\Request\Ping\Ping;
@@ -27,17 +29,17 @@ class Api
      */
     private $apiUrl;
 
-    /** @var \GuzzleHttp\Client */
+    /** @var Client */
     private $client;
 
     /**
      * Api constructor.
      *
-     * @param string      $username
-     * @param string      $apiKey
+     * @param string $username
+     * @param string $apiKey
      * @param string|null $apiUrl
      */
-    public function __construct($username, $apiKey, $apiUrl = null)
+    public function __construct(string $username, string $apiKey, $apiUrl = null)
     {
         $this->apiUrl = $apiUrl;
         $this->client = new Client([
@@ -50,7 +52,7 @@ public function __construct($username, $apiKey, $apiUrl = null)
      * Returns current API client with auth setup and base URL
      * @return Client
      */
-    public function client()
+    public function client(): Client
     {
         return $this->client;
     }
@@ -91,24 +93,34 @@ public function newsletter(int $emailId, array $contactLists): Newsletter
     /**
      * @return Ping
      */
-    public function ping()
+    public function ping(): Ping
     {
         return new Ping($this);
     }
 
     /**
      * @return Credentials
      */
-    public function credentials()
+    public function credentials(): Credentials
     {
         return new Credentials($this);
     }
 
-    public function customFields()
+    public function customFields(): CustomFields
     {
         return new CustomFields($this);
     }
 
+    public function eshopOrders(): EshopOrders
+    {
+        return new EshopOrders($this);
+    }
+
+    public function eshopOrdersBulk(): EshopOrdersBulk
+    {
+        return new EshopOrdersBulk($this);
+    }
+
     public function customEmailsBulk(): BulkCustomEmails
     {
         return new BulkCustomEmails($this);
@@ -123,5 +135,4 @@ public function transactionalEmails(): TransactionalEmails
     {
         return new TransactionalEmails($this);
     }
-
 }

src/Request/Eshops/AbstractEshopOrders.php

@@ -0,0 +1,90 @@
+<?php
+
+
+namespace SmartEmailing\v3\Request\Eshops;
+
+use JsonSerializable;
+use SmartEmailing\v3\Request\AbstractRequest;
+use SmartEmailing\v3\Request\Eshops\Model\Order;
+
+/**
+ * Class AbstractEshopOrders
+ * @package SmartEmailing\v3\Request\Eshops
+ */
+abstract class AbstractEshopOrders extends AbstractRequest implements JsonSerializable
+{
+	/**
+	 * @var Order[]
+	 */
+	protected array $orders = [];
+
+	/**
+	 * Creates Returns the newly created order
+	 *
+	 * @param $eshopName
+	 * @param $eshopCode
+	 * @param $emailAddress
+	 *
+	 * @return Order
+	 */
+	public function newOrder($eshopName, $eshopCode, $emailAddress): Order
+	{
+		$order = new Order($eshopName, $eshopCode, $emailAddress);
+		$this->addOrder($order);
+		return $order;
+	}
+
+	/**
+	 * @param Order $order
+	 *
+	 * @return AbstractEshopOrders
+	 */
+	public function addOrder(Order $order): AbstractEshopOrders
+	{
+		$this->orders[] = $order;
+		return $this;
+	}
+
+	/**
+	 * @return Order[]
+	 */
+	public function orders(): array
+	{
+		return $this->orders;
+	}
+
+	/**
+	 * @return array[]
+	 */
+	protected function options(): array
+	{
+		return [
+			'json' => $this->jsonSerialize()
+		];
+	}
+
+	/**
+	 * @return string
+	 */
+	protected function method(): string
+	{
+		return 'POST';
+	}
+
+	/**
+	 * @return array
+	 */
+	public function jsonSerialize(): array
+	{
+		return $this->toArray();
+	}
+	/**
+	 * Converts data to array
+	 * @return array
+	 */
+	public function toArray(): array
+	{
+		return $this->orders;
+	}
+
+}

src/Request/Eshops/EshopOrders.php

@@ -0,0 +1,55 @@
+<?php declare(strict_types=1);
+
+namespace SmartEmailing\v3\Request\Eshops;
+
+use SmartEmailing\v3\Request\Eshops\Model\Order;
+
+/**
+ * Class Orders
+ * @package SmartEmailing\v3\Request\Eshops
+ */
+class EshopOrders extends AbstractEshopOrders implements \JsonSerializable
+{
+	/**
+	 * @param  $order
+	 *
+	 * @return EshopOrders
+	 */
+	public function addOrder(Order $order): EshopOrders
+	{
+		$this->orders = [];
+		parent::addOrder($order);
+		return $this;
+	}
+
+	/**
+	 * @return Order|null
+	 */
+	public function order(): ?Order
+	{
+		if (count($this->orders)) {
+			return current($this->orders);
+		}
+		return null;
+	}
+
+	/**
+	 * @return string
+	 */
+	protected function endpoint(): string
+	{
+		return 'orders';
+	}
+
+	/**
+	 * Converts data to array
+	 * @return array
+	 */
+	public function toArray(): array
+	{
+		if (is_null($this->order())) {
+			return [];
+		}
+		return $this->order()->toArray();
+	}
+}

src/Request/Eshops/EshopOrdersBulk.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace SmartEmailing\v3\Request\Eshops;
+
+use SmartEmailing\v3\Request\Response;
+
+/**
+ * Class OrdersBulk
+ * Method is used to import orders in bulk. Up to 500 orders per request is allowed.
+ * This creates new activities which can be used for scoring, segmentation and automation.
+ *
+ * @package SmartEmailing\v3\Request\Eshops
+ */
+class EshopOrdersBulk extends AbstractEshopOrders implements \JsonSerializable
+{
+	/**
+	 * The maximum orders per single request
+	 * @var int
+	 */
+	public int $chunkLimit = 500;
+
+	/**
+	 * Will send multiple requests because of the 500 count limit
+	 * @inheritDoc
+	 */
+	public function send(): ?Response
+	{
+		// There is not enough contacts to enable chunk mode
+		if ($this->chunkLimit >= count($this->orders)) {
+			return parent::send();
+		}
+
+		return $this->sendInChunkMode();
+	}
+
+	/**
+	 * Sends contact list in chunk mode
+	 * @return Response
+	 */
+	protected function sendInChunkMode(): Response
+	{
+		// Store the original contact list
+		$originalFullOrdersList = $this->orders;
+		$lastResponse = null;
+
+		// Chunk the array of contacts send it in multiple requests
+		foreach (array_chunk($this->orders, $this->chunkLimit) as $orders) {
+			// Store the contacts that will be passed
+			$this->orders = $orders;
+
+			$lastResponse = parent::send();
+		}
+
+		// Restore to original array
+		$this->orders = $originalFullOrdersList;
+
+		return $lastResponse;
+	}
+
+	/**
+	 * @return string
+	 */
+	protected function endpoint(): string
+	{
+		return 'orders-bulk';
+	}
+
+}