Merge pull request #110 from Kit/add-subscriber-stats-method

Add `get_subscriber_stats` method

Author: n7studios

src/ConvertKit_API_Traits.php

@@ -1044,6 +1044,20 @@ public function unsubscribe(int $subscriber_id)
         return $this->post(sprintf('subscribers/%s/unsubscribe', $subscriber_id));
     }
 
+    /**
+     * Get the email statistics for a specific subscriber.
+     *
+     * @param integer $id Subscriber ID.
+     *
+     * @see https://developers.kit.com/api-reference/subscribers/list-stats-for-a-subscriber
+     *
+     * @return mixed|object
+     */
+    public function get_subscriber_stats(int $id)
+    {
+        return $this->get(sprintf('subscribers/%s/stats', $id));
+    }
+
     /**
      * Get a list of the tags for a subscriber.
      *

tests/ConvertKitAPITest.php

@@ -1775,6 +1775,49 @@ public function testUpdateTagNameWithBlankName()
         );
     }
 
+    /**
+     * Test that get_subscriber_stats() returns the expected data
+     * when using a valid subscriber ID.
+     *
+     * @since   2.2.1
+     *
+     * @return void
+     */
+    public function testGetSubscriberStats()
+    {
+        $result = $this->api->get_subscriber_stats(
+            id: (int) $_ENV['CONVERTKIT_API_SUBSCRIBER_ID']
+        );
+        $this->assertArrayHasKey('subscriber', get_object_vars($result));
+        $this->assertArrayHasKey('id', get_object_vars($result->subscriber));
+        $this->assertArrayHasKey('stats', get_object_vars($result->subscriber));
+        $this->assertArrayHasKey('sent', get_object_vars($result->subscriber->stats));
+        $this->assertArrayHasKey('opened', get_object_vars($result->subscriber->stats));
+        $this->assertArrayHasKey('clicked', get_object_vars($result->subscriber->stats));
+        $this->assertArrayHasKey('bounced', get_object_vars($result->subscriber->stats));
+        $this->assertArrayHasKey('open_rate', get_object_vars($result->subscriber->stats));
+        $this->assertArrayHasKey('click_rate', get_object_vars($result->subscriber->stats));
+        $this->assertArrayHasKey('last_sent', get_object_vars($result->subscriber->stats));
+        $this->assertArrayHasKey('last_opened', get_object_vars($result->subscriber->stats));
+        $this->assertArrayHasKey('last_clicked', get_object_vars($result->subscriber->stats));
+        $this->assertArrayHasKey('sends_since_last_open', get_object_vars($result->subscriber->stats));
+        $this->assertArrayHasKey('sends_since_last_click', get_object_vars($result->subscriber->stats));
+    }
+
+    /**
+     * Test that get_subscriber_stats() throws a ClientException when an invalid
+     * subscriber ID is specified.
+     *
+     * @since   2.2.1
+     *
+     * @return void
+     */
+    public function testGetSubscriberStatsWithInvalidSubscriberID()
+    {
+        $this->expectException(ClientException::class);
+        $result = $this->api->get_subscriber_stats(12345);
+    }
+
     /**
      * Test that tag_subscriber_by_email() returns the expected data.
      *