Premium Analytics: add Stats followers endpoint

projects/packages/premium-analytics/changelog/add-stats-followers-endpoint

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Stats: Add followers report hook.

projects/packages/premium-analytics/packages/data/src/hooks/__tests__/stats-exports.test.ts

@@ -20,6 +20,7 @@ const statsHookNames = [
 	'useStatsAppDashboardModuleSettingsMutation',
 	'useStatsAppPlanUsage',
 	'useStatsArchives',
+	'useStatsFollowers',
 	'useStatsComments',
 	'useStatsSubscribers',
 	'useStatsSubscribersCounts',

projects/packages/premium-analytics/packages/data/src/hooks/index.ts

@@ -37,6 +37,8 @@ export type {
 	StatsAppPlanUsage,
 } from './use-stats-app-plan-usage';
 export { useStatsArchives, type StatsArchivesResponse } from './use-stats-archives';
+export { useStatsFollowers } from './use-stats-followers';
+export type { StatsFollowersParams, StatsFollowersResponse } from './use-stats-followers';
 export {
 	useStatsComments,
 	type StatsCommentsParams,

projects/packages/premium-analytics/packages/data/src/hooks/use-stats-followers.ts

@@ -0,0 +1,14 @@
+/**
+ * Internal dependencies
+ */
+import { statsFollowersQuery } from '../queries/stats-followers-query';
+import { useStatsQuery } from './use-stats-query';
+import type { UseStatsOptions } from './use-stats-report';
+import type { StatsFollowersParams } from '../queries/stats-followers-query';
+
+export type { StatsFollowersResponse } from '../queries/stats-followers-query';
+export type { StatsFollowersParams } from '../queries/stats-followers-query';
+
+export function useStatsFollowers( params: StatsFollowersParams = {}, options?: UseStatsOptions ) {
+	return useStatsQuery( statsFollowersQuery( params ), options );
+}

projects/packages/premium-analytics/packages/data/src/index.ts

@@ -42,6 +42,8 @@ export type {
 	StatsAppPlanUsage,
 } from './hooks/use-stats-app-plan-usage';
 export { useStatsArchives, type StatsArchivesResponse } from './hooks/use-stats-archives';
+export { useStatsFollowers } from './hooks/use-stats-followers';
+export type { StatsFollowersParams, StatsFollowersResponse } from './hooks/use-stats-followers';
 export {
 	useStatsComments,
 	type StatsCommentsParams,
@@ -130,6 +132,9 @@ export type {
 	StatsCommentsRawPost,
 	StatsCommentsRawResponse,
 	StatsFileDownloadsItem,
+	StatsFollowersItem,
+	StatsFollowersRawItem,
+	StatsFollowersRawResponse,
 	StatsItemAction,
 	StatsLocationsItem,
 	StatsDevicesItem,

projects/packages/premium-analytics/packages/data/src/processing/stats/__fixtures__/followers.ts

@@ -0,0 +1,35 @@
+import type { StatsFollowersRawResponse } from '../followers';
+
+export const followersFixture = {
+	page: 1,
+	pages: 1,
+	total: 125,
+	total_email: 5,
+	total_wpcom: 120,
+	is_owner_subscribed: false,
+	subscribers: [
+		{
+			ID: 111,
+			label: 'reader@example.com',
+			avatar: 'https://secure.gravatar.com/avatar/example?s=96',
+			url: null,
+			follow_data: null,
+			date_subscribed: '2026-06-16T18:53:05+00:00',
+		},
+		{
+			ID: 222,
+			display_name: 'Jane Reader',
+			avatar: null,
+			url: 'https://example.com',
+			follow_data: {
+				params: {
+					site_id: 123,
+					is_following: false,
+				},
+			},
+			date_subscribed: '2026-06-15T10:30:00+00:00',
+			email_subscription_id: 333,
+			subscription_id: 222,
+		},
+	],
+} satisfies StatsFollowersRawResponse;

projects/packages/premium-analytics/packages/data/src/processing/stats/__tests__/followers.test.ts

@@ -0,0 +1,74 @@
+import { sanitizeStatsFollowersResponse } from '..';
+import { followersFixture } from '../__fixtures__/followers';
+
+describe( 'Stats followers normalizer', () => {
+	it( 'normalizes followers subscriber rows', () => {
+		const result = sanitizeStatsFollowersResponse( followersFixture );
+
+		expect( result.summary ).toEqual( {
+			page: 1,
+			pages: 1,
+			total: 125,
+			total_email: 5,
+			total_wpcom: 120,
+			is_owner_subscribed: false,
+		} );
+		expect( result.data ).toHaveLength( 1 );
+		expect( result.data[ 0 ].items[ 0 ] ).toEqual( {
+			id: 111,
+			label: 'reader@example.com',
+			value: {
+				type: 'relative-date',
+				value: '2026-06-16T18:53:05+00:00',
+			},
+			iconClassName: 'avatar-user',
+			icon: 'https://secure.gravatar.com/avatar/example?d=mm',
+			link: null,
+			date_subscribed: '2026-06-16T18:53:05+00:00',
+			subscription_id: 111,
+			actions: [ { type: 'follow', data: false } ],
+			children: null,
+		} );
+		expect( result.data[ 0 ].items[ 1 ] ).toEqual(
+			expect.objectContaining( {
+				id: 333,
+				label: 'Jane Reader',
+				icon: null,
+				link: 'https://example.com',
+				subscription_id: 333,
+				actions: [
+					{
+						type: 'follow',
+						data: {
+							site_id: 123,
+							is_following: false,
+						},
+					},
+				],
+			} )
+		);
+	} );
+
+	it( 'returns an empty report for missing subscribers', () => {
+		expect(
+			sanitizeStatsFollowersResponse( {
+				page: 1,
+				pages: 1,
+				total: 0,
+				total_email: 0,
+				total_wpcom: 0,
+				is_owner_subscribed: false,
+			} )
+		).toEqual( {
+			summary: {
+				page: 1,
+				pages: 1,
+				total: 0,
+				total_email: 0,
+				total_wpcom: 0,
+				is_owner_subscribed: false,
+			},
+			data: [],
+		} );
+	} );
+} );

projects/packages/premium-analytics/packages/data/src/processing/stats/followers.ts

@@ -0,0 +1,115 @@
+import {
+	coerceStatsArray,
+	coerceStatsRecord,
+	createStatsListDataPoint,
+	normalizeStatsSummary,
+} from './utils';
+import type {
+	StatsItemAction,
+	StatsNormalizedItemBase,
+	StatsNormalizedReport,
+	StatsRecord,
+} from './types';
+import type { StatsQueryParams } from '../../utils/stats-params';
+
+type StatsFollowersValue = {
+	type: 'relative-date';
+	value?: string;
+};
+
+type StatsFollowersFollowData = {
+	params?: unknown;
+};
+
+export type StatsFollowersRawItem = {
+	ID?: number;
+	label?: string;
+	display_name?: string;
+	name?: string;
+	email?: string;
+	avatar?: string | null;
+	url?: string | null;
+	follow_data?: StatsFollowersFollowData | null;
+	date_subscribed?: string;
+	email_subscription_id?: number;
+	subscription_id?: number;
+	wpcom_subscription_id?: number;
+};
+
+export type StatsFollowersRawResponse = {
+	page?: number;
+	pages?: number;
+	total?: number;
+	total_email?: number;
+	total_wpcom?: number;
+	is_owner_subscribed?: boolean;
+	subscribers?: StatsFollowersRawItem[];
+};
+
+export interface StatsFollowersItem extends StatsNormalizedItemBase< null > {
+	id?: number;
+	label: string;
+	value: StatsFollowersValue;
+	iconClassName: string;
+	icon: string | null;
+	link: string | null;
+	date_subscribed?: string;
+	subscription_id?: number;
+	actions: StatsItemAction[];
+}
+
+function parseAvatar( avatar?: string | null ) {
+	if ( ! avatar ) {
+		return null;
+	}
+
+	const [ avatarBaseUrl ] = avatar.split( '?' );
+
+	return `${ avatarBaseUrl }?d=mm`;
+}
+
+function getSubscriptionId( item: StatsFollowersRawItem ) {
+	return (
+		item.email_subscription_id || item.subscription_id || item.wpcom_subscription_id || item.ID
+	);
+}
+
+export function sanitizeStatsFollowersResponse(
+	response: unknown,
+	query?: StatsQueryParams
+): StatsNormalizedReport< StatsFollowersItem > {
+	const payload = coerceStatsRecord( response ) as StatsFollowersRawResponse & StatsRecord;
+	const subscribers = coerceStatsArray< StatsFollowersRawItem >( payload.subscribers );
+	const items = subscribers.map( item => ( {
+		id: getSubscriptionId( item ),
+		label: item.label ?? item.display_name ?? item.name ?? item.email ?? '',
+		value: {
+			type: 'relative-date' as const,
+			value: item.date_subscribed,
+		},
+		iconClassName: 'avatar-user',
+		icon: parseAvatar( item.avatar ),
+		link: item.url ?? null,
+		date_subscribed: item.date_subscribed,
+		subscription_id: getSubscriptionId( item ),
+		actions: [
+			{
+				type: 'follow',
+				data: coerceStatsRecord( item.follow_data ).params ?? false,
+			},
+		],
+		children: null,
+	} ) );
+
+	return {
+		summary: normalizeStatsSummary( {
+			page: payload.page,
+			pages: payload.pages,
+			total: payload.total,
+			total_email: payload.total_email,
+			total_wpcom: payload.total_wpcom,
+			is_owner_subscribed: payload.is_owner_subscribed,
+		} ),
+		data: items.length ? [ createStatsListDataPoint( response, query, items ) ] : [],
+	};
+}

projects/packages/premium-analytics/packages/data/src/processing/stats/index.ts

@@ -20,6 +20,7 @@ export { sanitizeStatsUtmResponse } from './utm';
 export { sanitizeStatsEmailSummaryResponse } from './email-summary';
 export { sanitizeStatsEmailBreakdownResponse } from './email-breakdown';
 export { sanitizeStatsArchivesResponse } from './archives';
+export { sanitizeStatsFollowersResponse } from './followers';
 export { sanitizeStatsCommentsResponse } from './comments';
 export {
 	sanitizeStatsSubscribersResponse,
@@ -61,6 +62,11 @@ export type { StatsUtmItem, StatsUtmParam, StatsUtmTopPostItem } from './utm';
 export type { StatsEmailSummaryItem } from './email-summary';
 export type { StatsEmailBreakdownItem } from './email-breakdown';
 export type { StatsArchivesItem } from './archives';
+export type {
+	StatsFollowersItem,
+	StatsFollowersRawItem,
+	StatsFollowersRawResponse,
+} from './followers';
 export type {
 	StatsDevicesItem,
 	StatsDevicesResponse,

projects/packages/premium-analytics/packages/data/src/processing/stats/types.ts

@@ -5,6 +5,7 @@ import type { StatsDevicesItem } from './devices';
 import type { StatsEmailBreakdownItem } from './email-breakdown';
 import type { StatsEmailSummaryItem } from './email-summary';
 import type { StatsFileDownloadsItem } from './file-downloads';
+import type { StatsFollowersItem } from './followers';
 import type { StatsLocationsItem } from './locations';
 import type { StatsReferrersItem } from './referrers';
 import type { StatsSearchTermsItem } from './search-terms';
@@ -37,6 +38,7 @@ export type StatsNormalizedItem =
 	| StatsEmailSummaryItem
 	| StatsEmailBreakdownItem
 	| StatsArchivesItem
+	| StatsFollowersItem
 	| StatsCommentsItem
 	| StatsTagsItem
 	| StatsDevicesItem;

projects/packages/premium-analytics/packages/data/src/queries/__tests__/stats-queries.test.ts

@@ -5,6 +5,7 @@ import { statsAppProxyQuery } from '../stats-app-query';
 import { statsArchivesQuery } from '../stats-archives-query';
 import { statsCommentsQuery } from '../stats-comments-query';
 import { statsDevicesQuery } from '../stats-devices-query';
+import { statsFollowersQuery } from '../stats-followers-query';
 import { STATS_HIGHLIGHTS_STALE_TIME, statsHighlightsQuery } from '../stats-highlights-query';
 import { statsInsightsQuery } from '../stats-insights-query';
 import { statsLocationsQuery } from '../stats-locations-query';
@@ -241,6 +242,40 @@ describe( 'Stats query factories', () => {
 		);
 	} );
 
+	it( 'builds followers query keys from Calypso endpoint defaults', () => {
+		const query = statsFollowersQuery();
+
+		expect( query.queryKey ).toEqual( [
+			'stats',
+			'followers',
+			'1.1',
+			'stats/followers',
+			'GET',
+			{ type: 'all', filter_admin: false, max: 10 },
+			undefined,
+			'followers',
+		] );
+	} );
+
+	it( 'includes followers endpoint-specific params in query keys', () => {
+		const query = statsFollowersQuery( {
+			type: 'wpcom',
+			filter_admin: true,
+			max: 20,
+		} );
+
+		expect( query.queryKey ).toEqual( [
+			'stats',
+			'followers',
+			'1.1',
+			'stats/followers',
+			'GET',
+			{ type: 'wpcom', filter_admin: true, max: 20 },
+			undefined,
+			'followers',
+		] );
+	} );
+
 	it( 'builds app query keys without report param coercion', () => {
 		const query = statsAppProxyQuery( {
 			name: 'plan-usage',

projects/packages/premium-analytics/packages/data/src/queries/index.ts

@@ -26,6 +26,8 @@ export { statsVideoPlaysQuery } from './stats-video-plays-query';
 export { statsAppDashboardModuleSettingsQuery } from './stats-app-dashboard-module-settings-query';
 export { statsAppPlanUsageQuery } from './stats-app-plan-usage-query';
 export { statsArchivesQuery } from './stats-archives-query';
+export { statsFollowersQuery } from './stats-followers-query';
+export type { StatsFollowersParams, StatsFollowersResponse } from './stats-followers-query';
 export { statsCommentsQuery, type StatsCommentsParams } from './stats-comments-query';
 export {
 	statsSubscribersCountsQuery,