122 أسطر
3.5 KiB
Markdown
122 أسطر
3.5 KiB
Markdown
# 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.
|