Merge pull request #112 from Kit/add-get-stats-for-a-list-of-broadcasts-method

Add `get_broadcasts_stats` method

Author: n7studios

src/ConvertKit_API_Traits.php

@@ -1258,6 +1258,39 @@ public function get_broadcast_link_clicks(
         );
     }
 
+    /**
+     * List stats for a list of broadcasts.
+     *
+     * @param boolean $include_total_count To include the total count of records in the response, use true.
+     * @param string  $after_cursor        Return results after the given pagination cursor.
+     * @param string  $before_cursor       Return results before the given pagination cursor.
+     * @param integer $per_page            Number of results to return.
+     *
+     * @since 2.2.1
+     *
+     * @see https://developers.kit.com/api-reference/broadcasts/get-stats-for-a-list-of-broadcasts
+     *
+     * @return false|mixed
+     */
+    public function get_broadcasts_stats(
+        bool $include_total_count = false,
+        string $after_cursor = '',
+        string $before_cursor = '',
+        int $per_page = 100
+    ) {
+        // Send request.
+        return $this->get(
+            'broadcasts/stats',
+            $this->build_total_count_and_pagination_params(
+                [],
+                $include_total_count,
+                $after_cursor,
+                $before_cursor,
+                $per_page
+            )
+        );
+    }
+
     /**
      * Updates a broadcast.
      *

tests/ConvertKitAPITest.php

@@ -4327,6 +4327,94 @@ public function testGetBroadcastLinkClicksWithInvalidBroadcastID()
         $this->api->get_broadcast_link_clicks(12345);
     }
 
+    /**
+     * Test that get_broadcasts_stats() returns the expected data.
+     *
+     * @since   2.2.1
+     *
+     * @return void
+     */
+    public function testGetBroadcastsStats()
+    {
+        // Get broadcasts stats.
+        $result = $this->api->get_broadcasts_stats(
+            per_page: 1
+        );
+
+        // Assert broadcasts and pagination exist.
+        $this->assertDataExists($result, 'broadcasts');
+        $this->assertPaginationExists($result);
+
+        // Assert a single broadcast was returned.
+        $this->assertCount(1, $result->broadcasts);
+
+        // Store the Broadcast ID to check it's different from the next broadcast.
+        $id = $result->broadcasts[0]->id;
+
+        // Assert has_previous_page and has_next_page are correct.
+        $this->assertFalse($result->pagination->has_previous_page);
+        $this->assertTrue($result->pagination->has_next_page);
+
+        // Use pagination to fetch next page.
+        $result = $this->api->get_broadcasts_stats(
+            per_page: 1,
+            after_cursor: $result->pagination->end_cursor
+        );
+
+        // Assert broadcasts and pagination exist.
+        $this->assertDataExists($result, 'broadcasts');
+        $this->assertPaginationExists($result);
+
+        // Assert a single broadcast was returned.
+        $this->assertCount(1, $result->broadcasts);
+
+        // Assert the broadcast ID is different from the previous broadcast.
+        $this->assertNotEquals($id, $result->broadcasts[0]->id);
+
+        // Assert has_previous_page and has_next_page are correct.
+        $this->assertTrue($result->pagination->has_previous_page);
+        $this->assertTrue($result->pagination->has_next_page);
+
+        // Use pagination to fetch previous page.
+        $result = $this->api->get_broadcasts_stats(
+            per_page: 1,
+            before_cursor: $result->pagination->start_cursor
+        );
+
+        // Assert broadcasts and pagination exist.
+        $this->assertDataExists($result, 'broadcasts');
+        $this->assertPaginationExists($result);
+
+        // Assert a single webhook was returned.
+        $this->assertCount(1, $result->broadcasts);
+
+        // Assert the broadcast ID matches the first broadcast.
+        $this->assertEquals($id, $result->broadcasts[0]->id);
+    }
+
+    /**
+     * Test that get_broadcasts_stats() returns the expected data
+     * when the total count is included.
+     *
+     * @since   2.2.1
+     *
+     * @return void
+     */
+    public function testGetBroadcastsStatsWithTotalCount()
+    {
+        $result = $this->api->get_broadcasts_stats(
+            include_total_count: true
+        );
+
+        // Assert broadcasts and pagination exist.
+        $this->assertDataExists($result, 'broadcasts');
+        $this->assertPaginationExists($result);
+
+        // Assert total count is included.
+        $this->assertArrayHasKey('total_count', get_object_vars($result->pagination));
+        $this->assertGreaterThan(0, $result->pagination->total_count);
+    }
+
     /**
      * Test that update_broadcast() throws a ClientException when an invalid
      * broadcast ID is specified.