Added new top referrers endpoint for post analytics (#23149)

ref
https://linear.app/ghost/issue/PROD-1542/adjust-conversion-attribution-to-reflect-free-members-and-paid-members

On the new Post Analytics page, we display a table of the top sources
for a particular post, sorted by free members, paid members and MRR.
This commit adds the API endpoint for this data, and wires it up to the
frontend.

Author: cmraible

apps/admin-x-framework/src/api/stats.ts

@@ -1,4 +1,4 @@
-import {Meta, createQuery} from '../utils/api/hooks';
+import {Meta, createQuery, createQueryWithId} from '../utils/api/hooks';
 
 // Types
 
@@ -48,12 +48,24 @@ export type TopPostsStatsResponseType = {
     meta: Meta;
 };
 
+export type PostReferrerStatItem = {
+    source: string;
+    free_members: number;
+    paid_members: number;
+    mrr: number;
+};
+
+export type PostReferrersResponseType = {
+    stats: PostReferrerStatItem[];
+    meta: Meta;
+};
+
 // Requests
 
 const dataType = 'TopContentResponseType';
 const memberCountHistoryDataType = 'MemberCountHistoryResponseType';
 const topPostsStatsDataType = 'TopPostsStatsResponseType';
-
+const postReferrersDataType = 'PostReferrersResponseType';
 export const useTopContent = createQuery<TopContentResponseType>({
     dataType,
     path: '/stats/top-content/'
@@ -68,3 +80,8 @@ export const useTopPostsStats = createQuery<TopPostsStatsResponseType>({
     dataType: topPostsStatsDataType,
     path: '/stats/top-posts/'
 });
+
+export const usePostReferrers = createQueryWithId<PostReferrersResponseType>({
+    dataType: postReferrersDataType,
+    path: id => `/stats/posts/${id}/top-referrers`
+});

apps/posts/src/hooks/usePostReferrers.ts

@@ -0,0 +1,12 @@
+import {useMemo} from 'react';
+import {usePostReferrers as usePostReferrersAPI} from '@tryghost/admin-x-framework/api/stats';
+
+export const usePostReferrers = (postId: string) => {
+    const {data: postReferrerResponse, isLoading} = usePostReferrersAPI(postId);
+    const stats = useMemo(() => postReferrerResponse?.stats || [], [postReferrerResponse]);
+
+    return {
+        isLoading,
+        stats
+    };
+};

apps/posts/src/views/PostAnalytics/Growth.tsx

@@ -4,26 +4,18 @@ import PostAnalyticsContent from './components/PostAnalyticsContent';
 import PostAnalyticsHeader from './components/PostAnalyticsHeader';
 import PostAnalyticsLayout from './layout/PostAnalyticsLayout';
 import {Card, CardContent, CardDescription, CardHeader, CardTitle, LucideIcon, Separator, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, ViewHeader, ViewHeaderActions, formatNumber} from '@tryghost/shade';
-
+import {useParams} from '@tryghost/admin-x-framework';
+import {usePostReferrers} from '../../hooks/usePostReferrers';
 const STATS_DEFAULT_SOURCE_ICON_URL = 'https://static.ghost.org/v5.0.0/images/globe-icon.svg';
 
 interface postAnalyticsProps {}
 
 const Growth: React.FC<postAnalyticsProps> = () => {
     // const {isLoading: isConfigLoading} = useGlobalData();
+    const {postId} = useParams();
+    const {stats: postReferrers, isLoading} = usePostReferrers(postId || '');
     // const {range} = useGlobalData();
 
-    const isLoading = false;
-
-    const mockTopSources = [
-        {id: 'source-001', title: 'google.com', freeMembers: 17, paidMembers: 7, mrr: 8},
-        {id: 'source-002', title: 'twitter.com', freeMembers: 12, paidMembers: 5, mrr: 6},
-        {id: 'source-003', title: 'facebook.com', freeMembers: 9, paidMembers: 4, mrr: 5},
-        {id: 'source-004', title: 'linkedin.com', freeMembers: 8, paidMembers: 3, mrr: 4},
-        {id: 'source-005', title: 'reddit.com', freeMembers: 7, paidMembers: 2, mrr: 3},
-        {id: 'source-006', title: 'medium.com', freeMembers: 6, paidMembers: 2, mrr: 3}
-    ];
-
     return (
         <PostAnalyticsLayout>
             <ViewHeader className='items-end pb-4'>
@@ -55,7 +47,7 @@ const Growth: React.FC<postAnalyticsProps> = () => {
                                     <LucideIcon.CircleDollarSign strokeWidth={1.5} />
                                 </KpiCardIcon>
                                 <KpiCardLabel>MRR</KpiCardLabel>
-                                <KpiCardValue>+$180</KpiCardValue>
+                                <KpiCardValue>+${formatNumber(180)}</KpiCardValue>
                             </KpiCard>
                         </div>
                         <Card>
@@ -75,22 +67,22 @@ const Growth: React.FC<postAnalyticsProps> = () => {
                                         </TableRow>
                                     </TableHeader>
                                     <TableBody>
-                                        {mockTopSources.map(source => (
-                                            <TableRow key={source.id}>
+                                        {postReferrers?.map(row => (
+                                            <TableRow key={row.source}>
                                                 <TableCell>
-                                                    <a className='inline-flex items-center gap-2 font-medium' href={`https://${source.title}`} rel="noreferrer" target='_blank'>
+                                                    <a className='inline-flex items-center gap-2 font-medium' href={`https://${row.source}`} rel="noreferrer" target='_blank'>
                                                         <img
                                                             className="size-4"
-                                                            src={`https://www.faviconextractor.com/favicon/${source.title || 'direct'}?larger=true`}
+                                                            src={`https://www.faviconextractor.com/favicon/${row.source || 'direct'}?larger=true`}
                                                             onError={(e: React.SyntheticEvent<HTMLImageElement>) => {
                                                                 e.currentTarget.src = STATS_DEFAULT_SOURCE_ICON_URL;
                                                             }} />
-                                                        <span>{source.title || 'Direct'}</span>
+                                                        <span>{row.source || 'Direct'}</span>
                                                     </a>
                                                 </TableCell>
-                                                <TableCell className='text-right font-mono text-sm'>+{formatNumber(source.freeMembers)}</TableCell>
-                                                <TableCell className='text-right font-mono text-sm'>+{formatNumber(source.paidMembers)}</TableCell>
-                                                <TableCell className='text-right font-mono text-sm'>+${source.mrr}</TableCell>
+                                                <TableCell className='text-right font-mono text-sm'>+{formatNumber(row.free_members)}</TableCell>
+                                                <TableCell className='text-right font-mono text-sm'>+{formatNumber(row.paid_members)}</TableCell>
+                                                <TableCell className='text-right font-mono text-sm'>+${formatNumber(row.mrr)}</TableCell>
                                             </TableRow>
                                         ))}
                                     </TableBody>

ghost/core/core/server/api/endpoints/stats.js

@@ -167,6 +167,45 @@ const controller = {
         async query(frame) {
             return await statsService.api.getTopPosts(frame.options);
         }
+    },
+    postReferrersAlpha: {
+        headers: {
+            cacheInvalidate: false
+        },
+        options: [
+            'order',
+            'limit',
+            'date_from',
+            'date_to',
+            'timezone'
+        ],
+        data: [
+            'id'
+        ],
+        validation: {
+            data: {
+                id: {
+                    type: 'string',
+                    required: true
+                }
+            }
+        },
+        permissions: {
+            docName: 'posts',
+            method: 'browse'
+        },
+        cache: statsService.cache,
+        generateCacheKeyData(frame) {
+            return {
+                method: 'getReferrersForPost',
+                data: {
+                    id: frame.data.id
+                }
+            };
+        },
+        async query(frame) {
+            return await statsService.api.getReferrersForPost(frame.data.id, frame.options);
+        }
     }
 };