+ class="mailchimp-sf-button btn-primary btn-small">
diff --git a/includes/class-mailchimp-analytics.php b/includes/class-mailchimp-analytics.php
index 3d5ededb..7bb841a0 100644
--- a/includes/class-mailchimp-analytics.php
+++ b/includes/class-mailchimp-analytics.php
@@ -90,11 +90,20 @@ public function enqueue_scripts( $hook_suffix ) {
true
);
+ $dependencies = array( 'mailchimp_sf_chartjs', 'wp-i18n' );
+ $version = MCSF_VER;
+ if ( file_exists( MCSF_DIR . '/dist/js/analytics.asset.php' ) ) {
+ $asset = require MCSF_DIR . '/dist/js/analytics.asset.php';
+ $dependencies = $asset['dependencies'] ?? array();
+ $dependencies = array_merge( $dependencies, array( 'mailchimp_sf_chartjs' ) );
+ $version = $asset['version'] ?? MCSF_VER;
+ }
+
wp_enqueue_script(
'mailchimp_sf_analytics_js',
MCSF_URL . 'dist/js/analytics.js',
- array( 'mailchimp_sf_chartjs' ),
- MCSF_VER,
+ $dependencies,
+ $version,
true
);
diff --git a/includes/class-mailchimp-subscriber-activity.php b/includes/class-mailchimp-subscriber-activity.php
new file mode 100644
index 00000000..593e8e87
--- /dev/null
+++ b/includes/class-mailchimp-subscriber-activity.php
@@ -0,0 +1,328 @@
+ esc_html__( 'Unauthorized.', 'mailchimp' ) ), 403 );
+ }
+
+ check_ajax_referer( 'mailchimp_sf_analytics_admin_nonce', 'nonce' );
+
+ $list_id = isset( $_POST['list_id'] ) ? sanitize_text_field( wp_unslash( $_POST['list_id'] ) ) : '';
+ $date_from = isset( $_POST['date_from'] ) ? sanitize_text_field( wp_unslash( $_POST['date_from'] ) ) : '';
+ $date_to = isset( $_POST['date_to'] ) ? sanitize_text_field( wp_unslash( $_POST['date_to'] ) ) : '';
+
+ if ( empty( $list_id ) ) {
+ wp_send_json_error( array( 'message' => esc_html__( 'Please select a list.', 'mailchimp' ) ), 400 );
+ }
+
+ if ( ! $this->is_valid_date( $date_from ) || ! $this->is_valid_date( $date_to ) ) {
+ wp_send_json_error( array( 'message' => esc_html__( 'Invalid date range.', 'mailchimp' ) ), 400 );
+ }
+
+ if ( strtotime( $date_from ) > strtotime( $date_to ) ) {
+ wp_send_json_error( array( 'message' => esc_html__( 'Start date must be before end date.', 'mailchimp' ) ), 400 );
+ }
+
+ $raw = $this->fetch_activity( $list_id );
+
+ if ( is_wp_error( $raw ) ) {
+ wp_send_json_error( array( 'message' => $raw->get_error_message() ), 502 );
+ }
+
+ if ( ! is_array( $raw ) ) {
+ wp_send_json_error( array( 'message' => esc_html__( 'Unable to reach Mailchimp.', 'mailchimp' ) ), 502 );
+ }
+
+ $response = $this->filter_and_aggregate( $raw, $date_from, $date_to );
+
+ wp_send_json_success( $response );
+ }
+
+ /**
+ * Fetch (and cache) the raw list activity for a list.
+ *
+ * The Mailchimp Activity API always returns the most recent 180 days for a
+ * given list regardless of query params, so a single transient can serve
+ * multiple date-range requests within its TTL.
+ *
+ * @param string $list_id List ID.
+ * @return array|WP_Error Normalized list of `{ date, new_subscribers, unsubscribes }` or error.
+ */
+ public function fetch_activity( string $list_id ) {
+ $cache_key = self::CACHE_PREFIX . md5( $list_id );
+ $cached = get_transient( $cache_key );
+ if ( is_array( $cached ) ) {
+ return $cached;
+ }
+
+ $api = mailchimp_sf_get_api();
+ if ( ! $api ) {
+ return new WP_Error(
+ 'mailchimp_sf_not_connected',
+ esc_html__( 'Mailchimp account is not connected.', 'mailchimp' )
+ );
+ }
+
+ $response = $api->get( 'lists/' . rawurlencode( $list_id ) . '/activity', self::API_WINDOW_DAYS );
+
+ if ( is_wp_error( $response ) ) {
+ return $response;
+ }
+
+ if ( ! is_array( $response ) || ! isset( $response['activity'] ) || ! is_array( $response['activity'] ) ) {
+ return new WP_Error(
+ 'mailchimp_sf_invalid_response',
+ esc_html__( 'Unexpected response from Mailchimp.', 'mailchimp' )
+ );
+ }
+
+ $normalized = array();
+ foreach ( $response['activity'] as $row ) {
+ if ( empty( $row['day'] ) ) {
+ continue;
+ }
+ $normalized[] = array(
+ 'date' => sanitize_text_field( $row['day'] ),
+ 'new_subscribers' => isset( $row['subs'] ) ? (int) $row['subs'] : 0,
+ 'unsubscribes' => isset( $row['unsubs'] ) ? (int) $row['unsubs'] : 0,
+ );
+ }
+
+ set_transient( $cache_key, $normalized, self::CACHE_TTL );
+
+ return $normalized;
+ }
+
+ /**
+ * Filter the raw (180 day) dataset to the selected range and aggregate it
+ * into buckets appropriate for that range.
+ *
+ * When the requested range exceeds the API's 180-day window we intersect
+ * with `[today - 179, today]` (inclusive, site timezone) and flag the
+ * response as `limited`.
+ *
+ * @param array $raw Normalized rows from `fetch_activity()`.
+ * @param string $date_from `Y-m-d`.
+ * @param string $date_to `Y-m-d`.
+ * @return array Response payload.
+ */
+ public function filter_and_aggregate( array $raw, string $date_from, string $date_to ): array {
+ $tz = wp_timezone();
+ $from_dt = new DateTimeImmutable( $date_from, $tz );
+ $to_dt = new DateTimeImmutable( $date_to, $tz );
+ $today = ( new DateTimeImmutable( 'now', $tz ) )->setTime( 0, 0, 0 );
+ $api_oldest = $today->modify( '-' . ( self::API_WINDOW_DAYS - 1 ) . ' days' );
+
+ $requested_days = (int) $from_dt->diff( $to_dt )->days + 1;
+ $limited = $requested_days > self::API_WINDOW_DAYS;
+
+ $effective_from = $from_dt < $api_oldest ? $api_oldest : $from_dt;
+ $effective_to = $to_dt > $today ? $today : $to_dt;
+
+ $interval = $this->get_interval( $requested_days );
+
+ $buckets = array();
+ $total_new = 0;
+ $total_unsubs = 0;
+
+ if ( $effective_from <= $effective_to ) {
+ // Index API rows by date so missing days can be back-filled with zeros.
+ // The Mailchimp Activity API omits days with no subscribe/unsubscribe
+ // activity, which would otherwise leave gaps in the chart timeline.
+ $by_date = array();
+ foreach ( $raw as $row ) {
+ $by_date[ $row['date'] ] = $row;
+ }
+
+ $one_day = new DateInterval( 'P1D' );
+ $cursor = $effective_from;
+
+ while ( $cursor <= $effective_to ) {
+ $date = $cursor->format( 'Y-m-d' );
+ $new_subscribers = isset( $by_date[ $date ]['new_subscribers'] )
+ ? (int) $by_date[ $date ]['new_subscribers']
+ : 0;
+ $unsubscribes = isset( $by_date[ $date ]['unsubscribes'] )
+ ? (int) $by_date[ $date ]['unsubscribes']
+ : 0;
+
+ $key = $this->get_bucket_key( $date, $interval, $tz );
+ if ( ! isset( $buckets[ $key ] ) ) {
+ $buckets[ $key ] = array(
+ 'key' => $key,
+ 'label' => $this->get_bucket_label( $date, $interval, $tz ),
+ 'new_subscribers' => 0,
+ 'unsubscribes' => 0,
+ );
+ }
+
+ $buckets[ $key ]['new_subscribers'] += $new_subscribers;
+ $buckets[ $key ]['unsubscribes'] += $unsubscribes;
+
+ $total_new += $new_subscribers;
+ $total_unsubs += $unsubscribes;
+
+ $cursor = $cursor->add( $one_day );
+ }
+
+ ksort( $buckets );
+ }
+
+ return array(
+ 'interval' => $interval,
+ 'data' => array_values( $buckets ),
+ 'total_new' => $total_new,
+ 'total_unsubs' => $total_unsubs,
+ 'net_change' => $total_new - $total_unsubs,
+ 'limited' => $limited,
+ );
+ }
+
+ /**
+ * Pick an aggregation interval based on the requested range.
+ *
+ * @param int $days Inclusive day count of the requested range.
+ * @return string One of `daily|weekly|monthly|quarterly|yearly`.
+ */
+ public function get_interval( int $days ): string {
+ if ( $days <= 30 ) {
+ return 'daily';
+ }
+ if ( $days <= 90 ) {
+ return 'weekly';
+ }
+ if ( $days <= 365 ) {
+ return 'monthly';
+ }
+ if ( $days <= 365 * 3 ) {
+ return 'quarterly';
+ }
+ return 'yearly';
+ }
+
+ /**
+ * Build a stable sort key for the bucket a given date falls into.
+ *
+ * @param string $date `Y-m-d`.
+ * @param string $interval Interval name.
+ * @param DateTimeZone|null $tz Timezone.
+ * @return string
+ */
+ public function get_bucket_key( string $date, string $interval, $tz = null ): string {
+ $tz = $tz instanceof DateTimeZone ? $tz : wp_timezone();
+ $dt = new DateTimeImmutable( $date, $tz );
+
+ switch ( $interval ) {
+ case 'weekly':
+ // ISO week starts on Monday.
+ return $dt->format( 'o-\WW' );
+ case 'monthly':
+ return $dt->format( 'Y-m' );
+ case 'quarterly':
+ $quarter = (int) ceil( (int) $dt->format( 'n' ) / 3 );
+ return $dt->format( 'Y' ) . '-Q' . $quarter;
+ case 'yearly':
+ return $dt->format( 'Y' );
+ case 'daily':
+ default:
+ return $dt->format( 'Y-m-d' );
+ }
+ }
+
+ /**
+ * Build a human-readable label for the bucket a given date falls into.
+ *
+ * @param string $date `Y-m-d`.
+ * @param string $interval Interval name.
+ * @param DateTimeZone|null $tz Timezone.
+ * @return string
+ */
+ public function get_bucket_label( string $date, string $interval, $tz = null ): string {
+ $tz = $tz instanceof DateTimeZone ? $tz : wp_timezone();
+ $dt = new DateTimeImmutable( $date, $tz );
+
+ switch ( $interval ) {
+ case 'weekly':
+ $monday = $dt->modify( 'monday this week' );
+ if ( $monday > $dt ) {
+ $monday = $dt->modify( 'monday last week' );
+ }
+ return wp_date( 'M j', $monday->getTimestamp(), $tz );
+ case 'monthly':
+ return wp_date( 'M Y', $dt->getTimestamp(), $tz );
+ case 'quarterly':
+ $quarter = (int) ceil( (int) $dt->format( 'n' ) / 3 );
+ return 'Q' . $quarter . ' ' . $dt->format( 'Y' );
+ case 'yearly':
+ return $dt->format( 'Y' );
+ case 'daily':
+ default:
+ return wp_date( 'M j', $dt->getTimestamp(), $tz );
+ }
+ }
+
+ /**
+ * Validate a `Y-m-d` date string.
+ *
+ * @param string $date Candidate date string.
+ * @return bool
+ */
+ private function is_valid_date( string $date ): bool {
+ if ( '' === $date ) {
+ return false;
+ }
+ $dt = DateTimeImmutable::createFromFormat( 'Y-m-d', $date );
+ return $dt && $dt->format( 'Y-m-d' ) === $date;
+ }
+}
diff --git a/mailchimp.php b/mailchimp.php
index 6e47fa96..40b1a2d3 100644
--- a/mailchimp.php
+++ b/mailchimp.php
@@ -120,6 +120,11 @@ function () {
$analytics_data = new Mailchimp_Analytics_Data();
$analytics_data->init();
+// Subscriber activity (Mailchimp Activity API) data class.
+require_once plugin_dir_path( __FILE__ ) . 'includes/class-mailchimp-subscriber-activity.php';
+$subscriber_activity = new Mailchimp_Subscriber_Activity();
+$subscriber_activity->init();
+
// Deprecated functions.
require_once plugin_dir_path( __FILE__ ) . 'includes/mailchimp-deprecated-functions.php';
diff --git a/tests/cypress/config.js b/tests/cypress/config.js
index bc4b5d0e..09f47f57 100644
--- a/tests/cypress/config.js
+++ b/tests/cypress/config.js
@@ -28,6 +28,7 @@ module.exports = defineConfig({
'tests/cypress/e2e/connect.test.js',
'tests/cypress/e2e/settings/list.test.js',
'tests/cypress/e2e/settings/settings.test.js',
+ 'tests/cypress/e2e/settings/analytics.test.js',
'tests/cypress/e2e/submission/**.test.js',
'tests/cypress/e2e/validation/**.test.js',
'tests/cypress/e2e/block.test.js',
diff --git a/tests/cypress/e2e/settings/analytics.test.js b/tests/cypress/e2e/settings/analytics.test.js
index eef7a746..2a33d8ab 100644
--- a/tests/cypress/e2e/settings/analytics.test.js
+++ b/tests/cypress/e2e/settings/analytics.test.js
@@ -1,4 +1,11 @@
/* eslint-disable no-undef */
+const {
+ isSubscriberActivityRequest,
+ buildSuccessData,
+ wpJsonSuccess,
+ wpJsonError,
+} = require('../../support/functions/subscriberActivityAjax');
+
describe('Analytics admin page', () => {
before(() => {
cy.login();
@@ -122,6 +129,161 @@ describe('Analytics admin page', () => {
cy.get('#mailchimp-sf-list-filter').should('exist');
cy.get('#mailchimp-sf-list-filter option').should('have.length.greaterThan', 0);
});
+
+ describe('Subscriber activity chart (stubbed)', () => {
+ const analyticsUrl = '/wp-admin/admin.php?page=mailchimp_sf_analytics';
+
+ function stubSubscriberActivity(replyFn) {
+ cy.intercept('POST', '**/admin-ajax.php', (req) => {
+ if (!isSubscriberActivityRequest(req)) {
+ req.continue();
+ return;
+ }
+ const payload = typeof replyFn === 'function' ? replyFn(req) : replyFn;
+ req.reply({
+ statusCode: 200,
+ headers: { 'content-type': 'application/json; charset=UTF-8' },
+ body: payload,
+ });
+ }).as('subscriberActivity');
+ }
+
+ it('Subscriber activity section shell (headings, canvases)', () => {
+ stubSubscriberActivity(() => wpJsonSuccess(buildSuccessData()));
+ cy.visit(analyticsUrl);
+ cy.wait('@subscriberActivity');
+ cy.get('[data-section="subscriber-activity"]').should('be.visible');
+ cy.get('#mailchimp-sf-sa-title').contains('Subscriber change over time');
+ cy.get('#mailchimp-sf-sa-totals-title').contains(
+ 'Totals for the selected date range',
+ );
+ cy.get('#mailchimp-sf-sa-bar').should('exist');
+ cy.get('#mailchimp-sf-sa-donut').should('exist');
+ });
+
+ it('Success payload shows ready state and numeric totals', () => {
+ stubSubscriberActivity(() =>
+ wpJsonSuccess(
+ buildSuccessData({
+ total_new: 12,
+ total_unsubs: 4,
+ net_change: 8,
+ data: [
+ {
+ key: '2026-04-01',
+ label: 'Apr 1',
+ new_subscribers: 12,
+ unsubscribes: 4,
+ },
+ ],
+ }),
+ ),
+ );
+ cy.visit(analyticsUrl);
+ cy.wait('@subscriberActivity');
+ cy.get('[data-section="subscriber-activity"]').should('have.class', 'is-ready');
+ cy.get('[data-section="subscriber-activity"]').should(
+ 'not.have.class',
+ 'is-loading',
+ );
+ cy.get('[data-section="subscriber-activity"]').should('not.have.class', 'is-error');
+ cy.get('#mailchimp-sf-sa-net').should('contain', '+8');
+ cy.get('#mailchimp-sf-sa-total-new').should('have.text', '12');
+ cy.get('#mailchimp-sf-sa-total-unsubs').should('have.text', '4');
+ });
+
+ it('Empty data shows empty state', () => {
+ stubSubscriberActivity(() =>
+ wpJsonSuccess(
+ buildSuccessData({
+ data: [],
+ total_new: 0,
+ total_unsubs: 0,
+ net_change: 0,
+ }),
+ ),
+ );
+ cy.visit(analyticsUrl);
+ cy.wait('@subscriberActivity');
+ cy.get('[data-section="subscriber-activity"]').should('have.class', 'is-empty');
+ cy.get('#mailchimp-sf-sa-daterange').contains(
+ 'No data available for the selected date range',
+ );
+ cy.get('#mailchimp-sf-sa-overlay').contains(
+ 'No data available for this date range',
+ );
+ });
+
+ it('API error shows error banner', () => {
+ stubSubscriberActivity(() => wpJsonError('Stub API failure'));
+ cy.visit(analyticsUrl);
+ cy.wait('@subscriberActivity');
+ cy.get('[data-section="subscriber-activity"]').should('have.class', 'is-error');
+ cy.get('#mailchimp-sf-sa-error-banner').should('be.visible');
+ cy.get('#mailchimp-sf-sa-error-message').contains('Stub API failure');
+ });
+
+ it('Retry after error loads success', () => {
+ let n = 0;
+ stubSubscriberActivity(() => {
+ n += 1;
+ if (n === 1) {
+ return wpJsonError('First request fails');
+ }
+ return wpJsonSuccess(buildSuccessData());
+ });
+ cy.visit(analyticsUrl);
+ cy.wait('@subscriberActivity');
+ cy.get('[data-section="subscriber-activity"]').should('have.class', 'is-error');
+ cy.get('#mailchimp-sf-sa-error-retry').click();
+ cy.wait('@subscriberActivity');
+ cy.get('[data-section="subscriber-activity"]').should('have.class', 'is-ready');
+ cy.get('#mailchimp-sf-sa-error-banner').should('have.attr', 'hidden');
+ });
+
+ it('Limited range shows notice', () => {
+ stubSubscriberActivity(() =>
+ wpJsonSuccess(
+ buildSuccessData({
+ limited: true,
+ }),
+ ),
+ );
+ cy.visit(analyticsUrl);
+ cy.wait('@subscriberActivity');
+ cy.get('#mailchimp-sf-sa-notice')
+ .should('be.visible')
+ .and(
+ 'contain',
+ 'Mailchimp subscriber activity is only available for the last 180 days. Showing available data.',
+ );
+ });
+
+ it('Changing list filter triggers another subscriber activity request', function () {
+ stubSubscriberActivity(() => wpJsonSuccess(buildSuccessData()));
+ cy.visit(analyticsUrl);
+ cy.wait('@subscriberActivity');
+ cy.get('#mailchimp-sf-list-filter option').then(function ($options) {
+ const values = [...$options].map((o) => o.value).filter(Boolean);
+ if (values.length < 2) {
+ this.skip();
+ }
+ cy.get('#mailchimp-sf-list-filter').select(values[1]);
+ cy.wait('@subscriberActivity');
+ });
+ });
+
+ it('Applying a different date preset triggers another subscriber activity request', () => {
+ stubSubscriberActivity(() => wpJsonSuccess(buildSuccessData()));
+ cy.visit(analyticsUrl);
+ cy.wait('@subscriberActivity');
+ cy.get('#mailchimp-sf-date-picker-trigger').click();
+ cy.get('#mailchimp-sf-date-range').select('7');
+ cy.get('#mailchimp-sf-date-picker-apply').click();
+ cy.wait('@subscriberActivity');
+ cy.get('#mailchimp-sf-date-picker-label').should('have.text', 'Last 7 days');
+ });
+ });
});
describe('When not connected', () => {
@@ -134,8 +296,10 @@ describe('Analytics admin page', () => {
it('Analytics submenu is not visible', () => {
cy.visit('/wp-admin/');
cy.get('#adminmenu li#toplevel_page_mailchimp_sf_options').click();
- cy.get('#adminmenu li#toplevel_page_mailchimp_sf_options .wp-submenu')
- .should('not.contain', 'Analytics');
+ cy.get('#adminmenu li#toplevel_page_mailchimp_sf_options .wp-submenu').should(
+ 'not.contain',
+ 'Analytics',
+ );
});
after(() => {
diff --git a/tests/cypress/support/functions/subscriberActivityAjax.js b/tests/cypress/support/functions/subscriberActivityAjax.js
new file mode 100644
index 00000000..f62b2889
--- /dev/null
+++ b/tests/cypress/support/functions/subscriberActivityAjax.js
@@ -0,0 +1,80 @@
+/**
+ * Helpers for stubbing `mailchimp_sf_get_subscriber_activity` admin-ajax calls.
+ * fetch() uses FormData (multipart); match by substring or parsed fields.
+ *
+ * @param {object} req Cypress intercepted request
+ * @returns {boolean}
+ */
+function isSubscriberActivityRequest(req) {
+ const action = 'mailchimp_sf_get_subscriber_activity';
+ const { body } = req;
+ if (typeof body === 'string') {
+ return body.includes(action);
+ }
+ if (body && typeof body === 'object') {
+ if (body.action === action) {
+ return true;
+ }
+ }
+ return JSON.stringify(body ?? '').includes(action);
+}
+
+/**
+ * Build a minimal successful subscriber-activity payload for stubs.
+ *
+ * @param {object} overrides Partial payload.data from PHP filter_and_aggregate.
+ * @returns {object} wp_send_json_success-compatible inner `data` object.
+ */
+function buildSuccessData(overrides = {}) {
+ return {
+ interval: 'daily',
+ data: [
+ {
+ key: '2026-04-01',
+ label: 'Apr 1',
+ new_subscribers: 5,
+ unsubscribes: 2,
+ },
+ ],
+ total_new: 5,
+ total_unsubs: 2,
+ net_change: 3,
+ limited: false,
+ ...overrides,
+ };
+}
+
+/**
+ * Wrap inner data as a WordPress `wp_send_json_success`-shaped response body.
+ *
+ * @param {object} data Inner success payload (from buildSuccessData).
+ * @returns {object} Full JSON body for the browser.
+ */
+function wpJsonSuccess(data) {
+ return {
+ success: true,
+ data,
+ };
+}
+
+/**
+ * Build a WordPress `wp_send_json_error`-shaped response body for stubs.
+ *
+ * @param {string} message Error message exposed to the UI.
+ * @returns {object} Full JSON body for wp_send_json_error shape.
+ */
+function wpJsonError(message) {
+ return {
+ success: false,
+ data: {
+ message,
+ },
+ };
+}
+
+module.exports = {
+ isSubscriberActivityRequest,
+ buildSuccessData,
+ wpJsonSuccess,
+ wpJsonError,
+};