Artist Dashboard API

This endpoint powers the Flutter artist profile dashboard for the currently authenticated user.

Endpoint

GET /api/v1/users/me/dashboard

Headers

Authorization: Bearer <accessToken>

Notes

This endpoint is private to the authenticated user.
It does not accept a userId parameter.
It does not expose another user's private analytics.
It keeps the existing GET /api/v1/users/:id/profile-overview endpoint unchanged.
Earnings, audience non-followers, and chart data are not faked. They return safe empty/default values until dedicated analytics storage exists.

Success Response Example

{
  "profile": {
    "_id": "665f00000000000000000001",
    "coverImage": "",
    "avatar": "",
    "name": "Artist Name",
    "stageName": "Stage Name",
    "bio": "Short artist bio",
    "isVerified": false
  },
  "stats": {
    "followersCount": 120,
    "followingCount": 45,
    "postsCount": 12,
    "collaborationsCount": 2,
    "viewCount": 3000,
    "playCount": 980,
    "listenCount": 980,
    "likesCount": 220,
    "commentsCount": 40,
    "savesCount": 18,
    "sharesCount": 11,
    "engagementRate": 7.26,
    "scorePercentage": 0,
    "earnings": 0
  },
  "audience": {
    "followers": 120,
    "nonFollowers": 0,
    "newFollowersThisWeek": 4,
    "newFollowersThisMonth": 19
  },
  "engagementChart": [],
  "topContent": [
    {
      "_id": "665f00000000000000000002",
      "postType": "audio",
      "thumbnailUrl": "",
      "displayUrl": "",
      "content": "New track",
      "viewCount": 1000,
      "playCount": 600,
      "likesCount": 90,
      "commentsCount": 10,
      "savesCount": 8,
      "engagementScore": 113,
      "createdAt": "2026-06-08T00:00:00.000Z"
    }
  ],
  "recentActivity": [],
  "meta": {
    "generatedAt": "2026-06-08T00:00:00.000Z",
    "chartAvailable": false,
    "earningsAvailable": false,
    "audienceAnalyticsAvailable": false
  }
}

Flutter Model Suggestion

ArtistDashboard
ArtistDashboardProfile
ArtistDashboardStats
ArtistDashboardAudience
ArtistDashboardTopContent
ArtistDashboardRecentActivity
ArtistDashboardMeta

UI Sections

Profile header: use profile.coverImage, profile.avatar, profile.name, profile.stageName, profile.bio, profile.isVerified.
Stats cards: use stats.followersCount, stats.followingCount, stats.viewCount, stats.listenCount, stats.engagementRate.
Engagement chart: render only when meta.chartAvailable === true; otherwise show the empty state.
Top content list: use topContent.
Audience summary: use audience.followers, audience.nonFollowers, audience.newFollowersThisWeek, audience.newFollowersThisMonth.
Recent activity: use recentActivity.
Empty states: show clear UI for no posts, no analytics, chart unavailable, and earnings unavailable.

Empty States

No posts yet: stats.postsCount === 0.
No analytics yet: stats.viewCount === 0 && stats.playCount === 0.
Chart not available: meta.chartAvailable === false.
Earnings not available: meta.earningsAvailable === false.

Future Analytics Upgrade

Daily chart data requires event-level or snapshot storage. Recommended future collections:

post_view_events
post_play_events
post_engagement_events
daily_artist_analytics

Audience split requires viewer identity tracking per view/play event. Earnings requires a monetization/revenue module. Until those exist, the backend intentionally returns safe defaults instead of fake values.

3.5 KiB خام اللوم التاريخ