# Spotify Heavy Rotation API Test

POC for testing Spotify API integration to retrieve heavy rotation data.

## Setup

1. Install dependencies:
```bash
npm install
```

2. Create `.env` file from example:
```bash
cp .env.example .env
```

3. Add your Spotify app credentials to `.env`:
   - `SPOTIFY_CLIENT_ID` - Your Spotify app client ID
   - `SPOTIFY_CLIENT_SECRET` - Your Spotify app client secret

4. Generate OAuth tokens:
```bash
npm run auth
```
This will open your browser to authorize with Spotify and automatically save tokens to `.env`

## Usage

### Single User Test
Test with a single user's tokens (from `.env`):
```bash
npm test
```

### Multi-User Test
Test with multiple users' refresh tokens (configured in `.env`):
```bash
npm run test:multi
```

Configure multiple users by adding to `.env`:
```env
FAN_1_REFRESH_TOKEN=...
FAN_2_REFRESH_TOKEN=...
FAN_3_REFRESH_TOKEN=...
```

## What it does

- Validates/refreshes OAuth tokens automatically
- Fetches top tracks and artists for 3 time ranges:
  - Last 4 weeks (short_term)
  - Last 6 months (medium_term)
  - All time (long_term)
- Displays results with links to Spotify

## Project Structure

### Core Files
- `config.ts` - Configuration and type definitions
- `auth.ts` - Token management and refresh logic
- `spotify-client.ts` - Axios-based API client with auto-refresh
- `fetch-heavy-rotation.ts` - Heavy rotation data fetching

### Test Scripts
- `test.ts` - Single user test runner
- `multi-fan-test.ts` - Multi-user test runner
- `generate-tokens.ts` - OAuth token generation tool

### Configuration
- `multi-fan-config.ts` - Multi-user configuration loader
- `.env` - Environment variables (not committed)
- `.env.example` - Example environment variables template

### Documentation
- `docs/` - Implementation plans and API documentation