# Spotify API Test Plan - Heavy Rotation

## Objective
Create a minimal TypeScript proof-of-concept to verify we can:
1. Authenticate with Spotify API using client credentials
2. Use a stored OAuth token for a fan
3. Retrieve the fan's "heavy rotation" (top tracks/artists) data

## Prerequisites
- Spotify Client ID and Client Secret
- A stored OAuth token for a test fan account
- Node.js/TypeScript environment

## Test Scripts Structure

### 1. Configuration File (`config.ts`)
- Store/load Spotify client credentials
- Define API endpoints
- Type definitions for Spotify API responses

### 2. Authentication Script (`auth.ts`)
- Function to validate stored OAuth token
- Function to refresh token if needed (using refresh token)
- Token expiration checking

### 3. API Client Script (`spotify-client.ts`)
- Initialize Spotify API client with credentials
- Implement authenticated request wrapper
- Error handling for API calls

### 4. Heavy Rotation Fetcher (`fetch-heavy-rotation.ts`)
- Fetch user's top tracks (short/medium/long term)
- Fetch user's top artists (short/medium/long term)
- Parse and format the response data

### 5. Test Runner (`test.ts`)
- Main entry point
- Load credentials and stored token
- Execute API calls
- Display results in readable format

## API Endpoints to Test

### Top Tracks
```
GET https://api.spotify.com/v1/me/top/tracks
Parameters:
- time_range: short_term (4 weeks) | medium_term (6 months) | long_term (years)
- limit: 1-50
```

### Top Artists
```
GET https://api.spotify.com/v1/me/top/artists
Parameters:
- time_range: short_term | medium_term | long_term
- limit: 1-50
```

## Expected Output
For each test run, display:
- Authentication status
- Top 10 tracks with play counts (if available)
- Top 10 artists
- Time range used
- Any errors encountered

## Files to Create
1. `config.ts` - Configuration and types
2. `auth.ts` - Token management
3. `spotify-client.ts` - API client wrapper
4. `fetch-heavy-rotation.ts` - Heavy rotation logic
5. `test.ts` - Test runner
6. `package.json` - Dependencies (axios/node-fetch, dotenv)
7. `.env.example` - Example environment variables template

## Success Criteria
- Successfully authenticate with stored OAuth token
- Retrieve top tracks for at least one time range
- Retrieve top artists for at least one time range
- Handle API errors gracefully
- Output structured data that can be used in production

## Next Steps After POC
- Integrate with existing fan OAuth token storage
- Add rate limiting
- Cache results
- Build production-ready service