From 964bced182f070fe88aa60355dadc5ae2ec96b2c Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 18:37:49 +0800 Subject: [PATCH 1/3] Add `get_broadcasts_stats` method --- src/ConvertKit_API_Traits.php | 33 ++++++++++++++++++ tests/ConvertKitAPITest.php | 65 +++++++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+) diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index 71f2175..2576493 100644 --- a/src/ConvertKit_API_Traits.php +++ b/src/ConvertKit_API_Traits.php @@ -1196,6 +1196,39 @@ public function get_broadcast_stats(int $id) return $this->get(sprintf('broadcasts/%s/stats', $id)); } + /** + * 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. * diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index e05a025..e718be3 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -4190,6 +4190,71 @@ public function testGetBroadcastStatsWithInvalidBroadcastID() $this->api->get_broadcast_stats(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 update_broadcast() throws a ClientException when an invalid * broadcast ID is specified. From a93716af09036be2334a86cb92dbd00004a236e7 Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Tue, 30 Sep 2025 18:40:34 +0800 Subject: [PATCH 2/3] Add `testGetBroadcastsStatsWithTotalCount` test --- tests/ConvertKitAPITest.php | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index e718be3..82d5d41 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -4255,6 +4255,29 @@ public function testGetBroadcastsStats() $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. From 4e900445132f83fde6cde77ad9ab53e4e94d2b7b Mon Sep 17 00:00:00 2001 From: Tim Carr Date: Fri, 3 Oct 2025 10:57:44 +0800 Subject: [PATCH 3/3] Reinstate method and tests --- src/ConvertKit_API_Traits.php | 33 +++++++++++++ tests/ConvertKitAPITest.php | 88 +++++++++++++++++++++++++++++++++++ 2 files changed, 121 insertions(+) diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php index e08aaee..136009c 100644 --- a/src/ConvertKit_API_Traits.php +++ b/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. * diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index 1761569..75245a2 100644 --- a/tests/ConvertKitAPITest.php +++ b/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.