From 7a98b6f5307506dd4a83188785f08d04e78d7529 Mon Sep 17 00:00:00 2001
From: Oleksandr Mykhailenko <mihaskep@gmail.com>
Date: Mon, 15 Jul 2024 19:28:55 +0300
Subject: [PATCH] De 1255 api stats endpoint (#912)

* Add dependabot. Change php-cs-fixer

* Domains. V4

* Merge branch 'master' of github.com:mailgun/mailgun-php

# Conflicts:
#	src/Api/DomainV4.php

* API STATS Endpoint. In Progress

* Added stats api methods

* fix code
---
 src/Api/Stats.php                             |  80 +++++-
 .../Stats/AggregateCountriesResponse.php      |  58 +++++
 src/Model/Stats/AggregateDevicesResponse.php  |  57 ++++
 src/Model/Stats/AggregateResponse.php         |  58 +++++
 src/Model/Stats/AggregateResponseItem.php     | 243 ++++++++++++++++++
 src/Model/Stats/TotalResponse.php             |  14 +
 6 files changed, 506 insertions(+), 4 deletions(-)
 create mode 100644 src/Model/Stats/AggregateCountriesResponse.php
 create mode 100644 src/Model/Stats/AggregateDevicesResponse.php
 create mode 100644 src/Model/Stats/AggregateResponse.php
 create mode 100644 src/Model/Stats/AggregateResponseItem.php

diff --git a/src/Api/Stats.php b/src/Api/Stats.php
index 528b4bbe..1817c17f 100644
--- a/src/Api/Stats.php
+++ b/src/Api/Stats.php
@@ -11,23 +11,37 @@
 
 namespace Mailgun\Api;
 
+use Exception;
 use Mailgun\Assert;
+use Mailgun\Model\Stats\AggregateCountriesResponse;
+use Mailgun\Model\Stats\AggregateDevicesResponse;
+use Mailgun\Model\Stats\AggregateResponse;
 use Mailgun\Model\Stats\TotalResponse;
 use Psr\Http\Client\ClientExceptionInterface;
+use Psr\Http\Message\ResponseInterface;
 
 /**
  * @see https://documentation.mailgun.com/en/latest/api-stats.html
- *
  * @author Tobias Nyholm <tobias.nyholm@gmail.com>
  */
 class Stats extends HttpApi
 {
+    public const EVENT_ACCEPTED = 'accepted';
+    public const EVENT_DELIVERED = 'delivered';
+    public const EVENT_FAILED = 'failed';
+    public const EVENT_OPENED = 'opened';
+    public const EVENT_CLICKED = 'clicked';
+    public const EVENT_UNSUBSCRIBED = 'unsubscribed';
+    public const EVENT_COMPLAINED = 'complained';
+    public const EVENT_STORED = 'stored';
+
     /**
-     * @param  string                   $domain
-     * @param  array                    $params
-     * @param  array                    $requestHeaders
+     * @param string $domain
+     * @param array $params
+     * @param array $requestHeaders
      * @return TotalResponse|array
      * @throws ClientExceptionInterface
+     * @throws Exception
      */
     public function total(string $domain, array $params = [], array $requestHeaders = [])
     {
@@ -37,4 +51,62 @@ public function total(string $domain, array $params = [], array $requestHeaders
 
         return $this->hydrateResponse($response, TotalResponse::class);
     }
+
+    /**
+     * @param array $params
+     * @param array $requestHeaders
+     * @return TotalResponse|array
+     * @throws ClientExceptionInterface
+     * @throws Exception
+     */
+    public function totalAccount(array $params = [], array $requestHeaders = [])
+    {
+        Assert::keyExists($params, 'event', 'You must specify an event');
+
+        $response = $this->httpGet('/v3/stats/total', $params, $requestHeaders);
+
+        return $this->hydrateResponse($response, TotalResponse::class);
+    }
+
+    /**
+     * @param string $domain
+     * @param array $requestHeaders
+     * @return AggregateResponse
+     * @throws ClientExceptionInterface
+     * @throws Exception
+     */
+    public function aggregateCountsByESP(string $domain, array $requestHeaders = []): AggregateResponse
+    {
+        $response = $this->httpGet(sprintf('/v3/%s/aggregates/providers', rawurlencode($domain)), [], $requestHeaders);
+
+        return $this->hydrateResponse($response, AggregateResponse::class);
+    }
+
+    /**
+     * @param string $domain
+     * @param array $requestHeaders
+     * @return AggregateDevicesResponse
+     * @throws ClientExceptionInterface
+     * @throws Exception
+     */
+    public function aggregateByDevices(string $domain, array $requestHeaders = []): AggregateDevicesResponse
+    {
+        $response = $this->httpGet(sprintf('/v3/%s/aggregates/devices', rawurlencode($domain)), [], $requestHeaders);
+
+        return $this->hydrateResponse($response, AggregateDevicesResponse::class);
+    }
+
+    /**
+     * @param string $domain
+     * @param array $requestHeaders
+     * @return AggregateCountriesResponse
+     * @throws ClientExceptionInterface
+     * @throws Exception
+     */
+    public function aggregateByCountry(string $domain, array $requestHeaders = []): AggregateCountriesResponse
+    {
+        $response = $this->httpGet(sprintf('/v3/%s/aggregates/countries', rawurlencode($domain)), [], $requestHeaders);
+
+        return $this->hydrateResponse($response, AggregateCountriesResponse::class);
+    }
 }
diff --git a/src/Model/Stats/AggregateCountriesResponse.php b/src/Model/Stats/AggregateCountriesResponse.php
new file mode 100644
index 00000000..32b62280
--- /dev/null
+++ b/src/Model/Stats/AggregateCountriesResponse.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Stats;
+
+use Mailgun\Model\ApiResponse;
+
+final class AggregateCountriesResponse implements ApiResponse
+{
+    private array $countries = [];
+
+    private function __construct()
+    {
+    }
+
+    /**
+     * @param array $data
+     * @return self
+     * @throws \Exception
+     */
+    public static function create(array $data): self
+    {
+        $countries = [];
+        foreach ($data['countries'] as $country => $provider) {
+            $countries[] = AggregateResponseItem::create($provider + ['country' => $country]);
+        }
+        $model = new self();
+        $model->setCountries($countries);
+        return $model;
+    }
+
+    /**
+     * @return array|AggregateResponseItem[]
+     */
+    public function getCountries(): array
+    {
+        return $this->countries;
+    }
+
+    /**
+     * @param array $countries
+     * @return void
+     */
+    public function setCountries(array $countries): void
+    {
+        $this->countries = $countries;
+    }
+
+
+}
diff --git a/src/Model/Stats/AggregateDevicesResponse.php b/src/Model/Stats/AggregateDevicesResponse.php
new file mode 100644
index 00000000..e36c3819
--- /dev/null
+++ b/src/Model/Stats/AggregateDevicesResponse.php
@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Stats;
+
+use Mailgun\Model\ApiResponse;
+
+final class AggregateDevicesResponse implements ApiResponse
+{
+    private array $devices = [];
+
+    private function __construct()
+    {
+    }
+
+    /**
+     * @param array $data
+     * @return self
+     * @throws \Exception
+     */
+    public static function create(array $data): self
+    {
+        $devices = [];
+        foreach ($data['devices'] as $domain => $provider) {
+            $devices[] = AggregateResponseItem::create($provider + ['device' => $domain]);
+        }
+        $model = new self();
+        $model->setDevices($devices);
+        return $model;
+    }
+
+    /**
+     * @return array|AggregateResponseItem[]
+     */
+    public function getDevices(): array
+    {
+        return $this->devices;
+    }
+
+    /**
+     * @param array $devices
+     * @return void
+     */
+    public function setDevices(array $devices): void
+    {
+        $this->devices = $devices;
+    }
+
+}
diff --git a/src/Model/Stats/AggregateResponse.php b/src/Model/Stats/AggregateResponse.php
new file mode 100644
index 00000000..f0dc7123
--- /dev/null
+++ b/src/Model/Stats/AggregateResponse.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Stats;
+
+use Mailgun\Model\ApiResponse;
+
+final class AggregateResponse implements ApiResponse
+{
+    private array $providers = [];
+
+    private function __construct()
+    {
+    }
+
+    /**
+     * @param array $data
+     * @return self
+     * @throws \Exception
+     */
+    public static function create(array $data): self
+    {
+        $providers = [];
+        foreach ($data['providers'] as $domain => $provider) {
+            $providers[] = AggregateResponseItem::create($provider + ['domain' => $domain]);
+        }
+        $model = new self();
+        $model->setProviders($providers);
+
+        return $model;
+    }
+
+    /**
+     * @return array|AggregateResponseItem[]
+     */
+    public function getProviders(): array
+    {
+        return $this->providers;
+    }
+
+    /**
+     * @param array $providers
+     * @return void
+     */
+    public function setProviders(array $providers): void
+    {
+        $this->providers = $providers;
+    }
+
+}
diff --git a/src/Model/Stats/AggregateResponseItem.php b/src/Model/Stats/AggregateResponseItem.php
new file mode 100644
index 00000000..d683b66d
--- /dev/null
+++ b/src/Model/Stats/AggregateResponseItem.php
@@ -0,0 +1,243 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Stats;
+
+use Mailgun\Model\ApiResponse;
+
+final class AggregateResponseItem implements ApiResponse
+{
+    private int $accepted;
+    private int $clicked;
+    private int $complained;
+    private int $delivered;
+    private int $opened;
+    private int $uniqueClicked;
+    private int $uniqueOpened;
+    private int $unsubscribed;
+    private string $domain;
+    private string $device;
+    private string $country;
+
+
+    private function __construct()
+    {
+    }
+
+    /**
+     * @param array $data
+     * @return self
+     */
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->setClicked($data['clicked'] ?? 0);
+        $model->setComplained($data['complained'] ?? 0);
+        $model->setDelivered($data['delivered'] ?? 0);
+        $model->setOpened($data['opened'] ?? 0);
+        $model->setUniqueClicked($data['unique_clicked'] ?? 0);
+        $model->setUniqueOpened($data['unique_opened'] ?? 0);
+        $model->setUnsubscribed($data['unsubscribed'] ?? 0);
+        $model->setAccepted($data['accepted'] ?? 0);
+        $model->setDomain($data['domain'] ?? '');
+        $model->setDevice($data['device'] ?? '');
+        $model->setCountry($data['country'] ?? '');
+
+        return $model;
+    }
+
+    /**
+     * @return int
+     */
+    public function getAccepted(): int
+    {
+        return $this->accepted;
+    }
+
+    /**
+     * @param int $accepted
+     * @return void
+     */
+    public function setAccepted(int $accepted): void
+    {
+        $this->accepted = $accepted;
+    }
+
+    /**
+     * @return int
+     */
+    public function getClicked(): int
+    {
+        return $this->clicked;
+    }
+
+    /**
+     * @param int $clicked
+     * @return void
+     */
+    public function setClicked(int $clicked): void
+    {
+        $this->clicked = $clicked;
+    }
+
+    /**
+     * @return int
+     */
+    public function getComplained(): int
+    {
+        return $this->complained;
+    }
+
+    /**
+     * @param int $complained
+     * @return void
+     */
+    public function setComplained(int $complained): void
+    {
+        $this->complained = $complained;
+    }
+
+    /**
+     * @return int
+     */
+    public function getDelivered(): int
+    {
+        return $this->delivered;
+    }
+
+    /**
+     * @param int $delivered
+     * @return void
+     */
+    public function setDelivered(int $delivered): void
+    {
+        $this->delivered = $delivered;
+    }
+
+    /**
+     * @return int
+     */
+    public function getOpened(): int
+    {
+        return $this->opened;
+    }
+
+    /**
+     * @param int $opened
+     * @return void
+     */
+    public function setOpened(int $opened): void
+    {
+        $this->opened = $opened;
+    }
+
+    /**
+     * @return int
+     */
+    public function getUniqueClicked(): int
+    {
+        return $this->uniqueClicked;
+    }
+
+    /**
+     * @param int $uniqueClicked
+     * @return void
+     */
+    public function setUniqueClicked(int $uniqueClicked): void
+    {
+        $this->uniqueClicked = $uniqueClicked;
+    }
+
+    /**
+     * @return int
+     */
+    public function getUniqueOpened(): int
+    {
+        return $this->uniqueOpened;
+    }
+
+    /**
+     * @param int $uniqueOpened
+     * @return void
+     */
+    public function setUniqueOpened(int $uniqueOpened): void
+    {
+        $this->uniqueOpened = $uniqueOpened;
+    }
+
+    /**
+     * @return int
+     */
+    public function getUnsubscribed(): int
+    {
+        return $this->unsubscribed;
+    }
+
+    /**
+     * @param int $unsubscribed
+     * @return void
+     */
+    public function setUnsubscribed(int $unsubscribed): void
+    {
+        $this->unsubscribed = $unsubscribed;
+    }
+
+    /**
+     * @return string
+     */
+    public function getDomain(): string
+    {
+        return $this->domain;
+    }
+
+    /**
+     * @param string $domain
+     * @return void
+     */
+    public function setDomain(string $domain): void
+    {
+        $this->domain = $domain;
+    }
+
+    /**
+     * @return string
+     */
+    public function getDevice(): string
+    {
+        return $this->device;
+    }
+
+    /**
+     * @param string $device
+     * @return void
+     */
+    public function setDevice(string $device): void
+    {
+        $this->device = $device;
+    }
+
+    /**
+     * @return string
+     */
+    public function getCountry(): string
+    {
+        return $this->country;
+    }
+
+    /**
+     * @param string $country
+     * @return void
+     */
+    public function setCountry(string $country): void
+    {
+        $this->country = $country;
+    }
+}
diff --git a/src/Model/Stats/TotalResponse.php b/src/Model/Stats/TotalResponse.php
index ed23574f..e03565f0 100644
--- a/src/Model/Stats/TotalResponse.php
+++ b/src/Model/Stats/TotalResponse.php
@@ -27,6 +27,11 @@ private function __construct()
     {
     }
 
+    /**
+     * @param array $data
+     * @return self
+     * @throws \Exception
+     */
     public static function create(array $data): self
     {
         $stats = [];
@@ -45,16 +50,25 @@ public static function create(array $data): self
         return $model;
     }
 
+    /**
+     * @return \DateTimeImmutable|null
+     */
     public function getStart(): ?\DateTimeImmutable
     {
         return $this->start;
     }
 
+    /**
+     * @return \DateTimeImmutable|null
+     */
     public function getEnd(): ?\DateTimeImmutable
     {
         return $this->end;
     }
 
+    /**
+     * @return string|null
+     */
     public function getResolution(): ?string
     {
         return $this->resolution;