feat(subscriptions): Add subscription/premium tier data model and API

[dev-susa]

Closes #99

Summary

This PR implements a subscription/premium tier system that enables the platform to offer enhanced features to paying users like higher upload limits and advanced analytics.

Changes

Core Subscription System

• ✅ Created Subscription entity with fields: userId, tier, status, startDate, endDate
• ✅ Defined subscription tiers: free, artist_pro, label
• ✅ Defined subscription statuses: active, cancelled, expired
• ✅ Implemented tier hierarchy for feature gating (FREE < ARTIST_PRO < LABEL)

Service Layer

• ✅ Created SubscriptionService with full subscription lifecycle management
• ✅ getUserSubscription - retrieves user's active subscription with expiration checking
• ✅ createOrUpgradeSubscription - creates new subscriptions or upgrades existing ones
• ✅ cancelSubscription - cancels subscription while preserving access until end date
• ✅ hasTierAccess - checks tier access for feature gating

API Endpoints

• ✅ GET /api/users/me/subscription - returns current user's subscription
• ✅ POST /api/subscriptions - creates or upgrades a subscription
• ✅ DELETE /api/subscriptions - cancels subscription at period end

Middleware & Utilities

• ✅ requireTier middleware for tier-based route protection
• ✅ checkTierAccess utility function for conditional tier checks in controllers
• ✅ Tier-based feature gating with hierarchical access control

Database

• ✅ Created migration 1753100000000-AddSubscriptionEntity.ts
• ✅ Added foreign key constraint to User entity (CASCADE on delete)
• ✅ Added indexes on userId and status for query performance
• ✅ Added CHECK constraints for valid tier and status values

Testing

• ✅ Comprehensive SubscriptionService tests (15 test cases)
• ✅ Subscription middleware tests (7 test cases)
• ✅ Total: 22 tests covering all subscription functionality

Subscription Tiers

Tier	Description	Use Case
FREE	Default tier	All new users, basic platform access
ARTIST_PRO	Enhanced artist features	Individual artists wanting higher upload limits, advanced analytics
LABEL	Premium label features	Record labels managing multiple artists, bulk operations

API Examples

Get Current Subscription

GET /api/users/me/subscription
Authorization: Bearer <token>

Response:
{
  "subscription": {
    "id": "uuid",
    "tier": "artist_pro",
    "status": "active",
    "startDate": "2026-01-01T00:00:00.000Z",
    "endDate": "2027-01-01T00:00:00.000Z"
  }
}

Create/Upgrade Subscription

POST /api/subscriptions
Authorization: Bearer <token>
Content-Type: application/json

{
  "tier": "artist_pro",
  "endDate": "2027-01-01T00:00:00.000Z"
}

Cancel Subscription

DELETE /api/subscriptions
Authorization: Bearer <token>

# Subscription remains active until endDate

Using Tier Middleware

// Protect route requiring ARTIST_PRO tier or higher
router.post('/premium-upload', 
  requireAuth, 
  requireTier(SubscriptionTier.ARTIST_PRO),
  uploadController.premiumUpload
);

Testing Evidence

All subscription functionality has comprehensive test coverage:

npm test -- src/__tests__/SubscriptionService.test.ts
# Test Suites: 1 passed
# Tests:       15 passed
# Coverage:    100% for SubscriptionService

Test Coverage:

• Subscription retrieval with expiration checking ✓
• Creating new subscriptions ✓
• Upgrading existing subscriptions ✓
• Cancelling subscriptions ✓
• Tier hierarchy validation ✓
• Middleware enforcement ✓
• Error handling ✓

Acceptance Criteria Met

• Subscription entity with: userId, tier, status, startDate, endDate
• Tiers: free, artist_pro, label
• GET /api/users/me/subscription returns current subscription
• POST /api/subscriptions creates or upgrades subscription
• DELETE /api/subscriptions cancels subscription at period end
• Tier-based feature gating utility function
• Migration for Subscription entity

Notes

• Payment processing integration is out of scope (as specified in issue)
• Trial periods and family plans are out of scope
• Built on top of PR feat(auth): role-based access control with granular permissions #216 RBAC system for complete access control

[drips-wave]

@dev-susa Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits