Spotify API Integration

Relevant source files

The following files were used as context for generating this wiki page:

• lib/spotify/getIsrc.ts (Referenced in lib/songs/getSongsByIsrc.ts)
• lib/spotify/generateAccessToken.ts (Referenced in lib/songs/getSongsByIsrc.ts)
• lib/songs/getSongsByIsrc.ts
• lib/songs/generateTrackNotes.ts
• lib/spotify/getSpotifyFollowers.ts
• lib/spotify/validateSpotifyAlbumQuery.ts
• lib/spotify/validateSpotifyArtistQuery.ts
• types/spotify.types.ts
• evals/spotify-tools.eval.ts

The Spotify API Integration is a core module within the Recoup platform designed to fetch, validate, and process music industry data directly from Spotify's Web API. It enables the system to enrich internal track records via ISRC lookups, retrieve artist follower counts for analytics, and validate queries for album and artist metadata.

This integration serves as a foundational data source for the AI assistant and various internal services, facilitating tasks such as pitch creation, playlist research, and automated track note generation. It follows the project's standard handler-validator pattern for API endpoints while providing specialized utilities for song-to-artist linking.
Sources: lib/chat/const.ts:5-15, evals/spotify-tools.eval.ts:20-30, lib/songs/getSongsByIsrc.ts:25-35

Core Data Structures

The integration utilizes strongly-typed interfaces to ensure consistency across the data pipeline. These types map directly to Spotify's object schemas for artists and tracks.

Artist and Track Schemas

The system defines comprehensive types for Spotify entities, including metadata, popularity scores, and external identifiers like ISRCs.

Field	Type	Description
id	string	The Spotify ID for the entity.
uri	string	The Spotify URI for the entity.
name	string	The name of the track or artist.
popularity	number	A score from 0 to 100 representing current popularity.
external_ids.isrc	string	International Standard Recording Code (Tracks only).
followers.total	number	Total follower count (Artists only).

Sources: types/spotify.types.ts:1-20, types/spotify.types.ts:22-86

Architecture and Data Flow

The integration follows a modular flow where internal song data is enriched with Spotify metadata. This typically involves generating an access token, performing a lookup (e.g., via ISRC), and generating descriptive notes for the system's knowledge base.

ISRC Enrichment Flow

The following diagram illustrates how the system processes a list of songs to fetch corresponding Spotify data and generate track notes.

The flow ensures that every song processed through the internal library is updated with the latest name, album info, and popularity metrics from Spotify.
Sources: lib/songs/getSongsByIsrc.ts:21-65

Sequence: Follower Count Retrieval

This sequence shows the interaction between the internal API base and the Spotify search functionality to retrieve artist stats.

Key Components and Functions

Enrichment Utilities

The integration provides specialized functions to convert raw Spotify data into human-readable or system-compatible formats.

• generateTrackNotes(track): Takes a SpotifyTrack and produces a string summarizing the track's album, release date, popularity, and explicit status.
  Sources: lib/songs/generateTrackNotes.ts:11-25
• getSongsByIsrc(songs): A batch processing function that authenticates with Spotify and fetches track details for multiple ISRCs simultaneously using Promise.all.
  Sources: lib/songs/getSongsByIsrc.ts:21-45
• linkSongsToArtists(songs): Extracts artist names from Spotify track data, normalizes them, and links them to internal artist account IDs.
  Sources: lib/songs/linkSongsToArtists.ts:13-35

Validation and Security

Following the project's API standards, specific validators ensure that incoming requests for Spotify data contain the necessary parameters.

• validateSpotifyAlbumQuery: Validates that an id is present and optionally checks for market parameters using Zod.
  Sources: lib/spotify/validateSpotifyAlbumQuery.ts:11-20
• validateSpotifyArtistQuery: Ensures the required id parameter is provided for artist-specific lookups.
  Sources: lib/spotify/validateSpotifyArtistQuery.ts:11-18

Evaluation and Tool Usage

The project includes an evaluation suite to ensure the AI agent uses Spotify tools correctly. The AI is expected to use specific tools for data gathering before responding to user prompts.

Required AI Tools

The following tools are defined for the AI's Spotify-related tasks:

• get_spotify_search
• get_spotify_artist_top_tracks
• get_spotify_artist_albums

Sources: evals/spotify-tools.eval.ts:30-36

Summary

The Spotify API Integration provides a robust bridge between the Recoup platform and Spotify's vast music database. By utilizing a standardized pattern of authentication, validation, and enrichment, it ensures that artist managers and the AI assistant have access to accurate, up-to-date streaming metrics and track metadata. This integration is critical for release management, fan analysis, and automated marketing strategy generation.