npm package: @krishna2206/deezer-api
Description: TypeScript Deezer API client
Author: krishna2206
Latest version: 1.0.0

# Deezer API TypeScript Package

A comprehensive TypeScript client for the Deezer API, extracted from the ReFreezer project. This package provides full access to Deezer's music streaming and metadata APIs.

## Installation

```bash
npm install @krishna2206/deezer-api
```

## Usage

### Basic Setup

```typescript
import DeezerAPI from '@krishna2206/deezer-api';

const deezer = new DeezerAPI({
  language: 'en',
  country: 'US'
});

// Initialize with ARL token
await deezer.initialize('your_arl_token_here');
```

### Search

```typescript
// Search for music
const results = await deezer.search('Daft Punk');
console.log(results.tracks, results.albums, results.artists, results.playlists);

// Get search suggestions
const suggestions = await deezer.searchSuggestions('Daft');
```

### Tracks

```typescript
// Get track details
const track = await deezer.track('track_id');

// Add to favorites
await deezer.addFavoriteTrack('track_id');

// Get streaming URL
const { url, encrypted } = await deezer.getTrackUrl(trackData, quality);
```

### Albums

```typescript
// Get album details
const album = await deezer.album('album_id');

// Get user's favorite albums
const albums = await deezer.getAlbums();

// Add album to favorites
await deezer.addFavoriteAlbum('album_id');
```

### Artists

```typescript
// Get artist details
const artist = await deezer.artist('artist_id');

// Get artist discography
const discography = await deezer.discographyPage('artist_id');

// Get user's favorite artists
const artists = await deezer.getArtists();
```

### Playlists

```typescript
// Get playlist
const playlist = await deezer.playlist('playlist_id');

// Create new playlist
const playlistId = await deezer.createPlaylist('My Playlist', 'Description');

// Add track to playlist
await deezer.addToPlaylist('track_id', 'playlist_id');

// Get user's playlists
const playlists = await deezer.getPlaylists();
```

### Discovery

```typescript
// Get home page
const homePage = await deezer.homePage();

// Get Flow (personalized radio)
const flowTracks = await deezer.flow();

// Get smart radio for artist
const radioTracks = await deezer.smartRadio('artist_id');

// Get mix based on track
const mixTracks = await deezer.playMix('track_id');
```

### URL Parsing

```typescript
// Parse Deezer URLs
const linkInfo = await deezer.parseLink('https://www.deezer.com/track/123456');
if (linkInfo?.type === 'TRACK') {
  const track = await deezer.track(linkInfo.id!);
}
```

### Downloads

```typescript
import { TrackQuality } from '@krishna2206/deezer-api';
import fs from 'fs';
import path from 'path';

// Download a single track with progress tracking
const onProgress = (progress) => {
  console.log(`${progress.phase}: ${progress.percentage.toFixed(1)}%`);
  console.log(`Speed: ${progress.downloadSpeed} bytes/s`);
  console.log(`ETA: ${progress.timeRemaining} seconds`);
};

const result = await deezer.downloadTrack(
  'track_id',
  TrackQuality.MP3_320, // or TrackQuality.FLAC, TrackQuality.MP3_128
  onProgress
);

if (result.success) {
  const { audioData, trackData, coverData, filename } = result;
  
  // Handle the raw audio data as needed
  // For example, save to file:
  const filePath = path.join('./downloads', filename);
  fs.writeFileSync(filePath, Buffer.from(audioData));
  
  console.log('Downloaded:', filename);
  console.log('Track data:', trackData.SNG_TITLE);
  console.log('Has cover:', !!coverData);
} else {
  console.error('Download failed:', result.error);
}

// Download album cover
const coverData = await deezer.downloadAlbumCover('md5_hash', 1000);
```

## Download Progress Phases

The download progress callback provides detailed information about each phase:

- **fetching**: Getting track metadata from Deezer API
- **downloading**: Downloading the encrypted audio file with real-time progress
- **decrypting**: Decrypting the audio file (if encrypted)
- **complete**: Download finished successfully

Note: The API returns raw audio data, track metadata, and cover data. File saving and metadata addition should be handled by the consuming application for maximum flexibility.

## Authentication

You need a valid ARL (Authentication Record Locator) token to use this API. This token can be obtained by logging into Deezer through a web browser and extracting it from the cookies.

**Note**: This is for educational purposes only. Please respect Deezer's Terms of Service.

## License

MIT License - See LICENSE file for details.