# Artist Dashboard API

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

## Endpoint

`GET /api/v1/users/me/dashboard`

## Headers

```http
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

```json
{
  "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

1. Profile header: use `profile.coverImage`, `profile.avatar`, `profile.name`, `profile.stageName`, `profile.bio`, `profile.isVerified`.
2. Stats cards: use `stats.followersCount`, `stats.followingCount`, `stats.viewCount`, `stats.listenCount`, `stats.engagementRate`.
3. Engagement chart: render only when `meta.chartAvailable === true`; otherwise show the empty state.
4. Top content list: use `topContent`.
5. Audience summary: use `audience.followers`, `audience.nonFollowers`, `audience.newFollowersThisWeek`, `audience.newFollowersThisMonth`.
6. Recent activity: use `recentActivity`.
7. 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.