How novaantonsito/importador-spotify-tidal-cli works
Project Type and Purpose
• This is an open-source, Node.js/TypeScript CLI tool whose sole purpose is to import playlists from Spotify into Tidal.
• It exposes an interactive command-line interface, handles OAuth2 authentication flows for both services, retrieves playlist and track data, matches tracks intelligently, and then recreates playlists in Tidal.
File Structure
• Top-level files:
• index.ts – entry point that wires up the CLI
• package.json, tsconfig.json, vitest.config.ts – build/config files
• scripts/postinstall.js – handles credential file creation on first install
• src/cli – InteractiveMenu.ts and CLI index
• src/auth – OAuthServer.ts (embedded HTTP server), AuthManager.ts
• src/config – ConfigManager.ts, defaults, paths
• src/services – HTTP wrappers around Spotify and Tidal REST APIs
• src/matching – SongMatcher.ts implements search heuristics
• src/services/PlaylistImporter.ts & PlaylistSyncManager.ts – core orchestration logic
• src/models – typed interfaces for playlists, tracks, auth tokens
• src/utils – error handling, progress reporting, recovery
README Insights
• Uses OAuth2 with a local callback server at port 8888
• Configurable via credentials file in OS-specific path
• Interactive vs. “auto” modes, batch processing, retry logic, progress persistence
• No external database – all state is in memory or on disk for recovery
Main Components
A. CLI Layer
• InteractiveMenu
• CLI argument parser
B. Configuration Layer
• ConfigManager (reads/writes credentials.txt)
C. Authentication Layer
• OAuthServer (embedded HTTP server)
• AuthManager (handles token exchange, refresh)
D. Core Orchestration
• PlaylistImporter (loops over user-selected playlists)
• PlaylistSyncManager (manages import batches, retries)
E. Services Layer
• SpotifyService (fetch playlists, tracks via Spotify Web API)
• TidalService (search tracks, create playlists via Tidal API)
F. Matching Engine
• SongMatcher (string similarity, metadata heuristics)
G. Utilities
• ProgressReporter / ProgressRecovery
• ErrorHandler / ErrorLogger
H. External Systems
• Spotify API
• Tidal API
• File system (credentials.txt, optional resume state)
Component Relationships & Data Flow
1. User runs “npx spotify-tidal-importer” → CLI Layer
2. CLI → ConfigManager loads credentials or triggers postinstall flow
3. ConfigManager → OAuthServer starts on localhost:8888
4. CLI → AuthManager → directs user browser to Spotify & Tidal auth URLs
5. OAuthServer callback → AuthManager obtains tokens → ConfigManager persists tokens
6. PlaylistImporter ← CLI triggers “import” → PlaylistSyncManager
7. PlaylistSyncManager → SpotifyService.fetchUserPlaylists()
8. For each track:
• SongMatcher tries to find best match in TidalService.searchTrack()
• Matched Tidal track IDs collected in batches
• TidalService.createPlaylist() and addTracks()
9. ProgressReporter / ProgressRecovery update CLI display & disk state
10. On completion → Reporting summary to CLI
Architectural Patterns & Principles
• Modular layering (CLI → Auth → Config → Services → Matching → Utilities)
• Separation of concerns:
• Authentication isolated from business logic
• Services layer abstracts HTTP details
• matching algorithms decoupled from API calls
• Dependency injection via index.ts for easy testing
• Resiliency: retry logic, rate-limit handling, recovery from interruptions
Relevant Technologies
• Node.js, TypeScript
• OAuth2 (local HTTP server)
• RESTful HTTP clients (e.g., fetch/axios)
• CLI utilities (InteractiveMenu using readline or third-party library)
• File-based configuration in OS-specific paths
• Vitest for testing
Diagramming Recommendations
• Rectangles for internal modules (CLI, services, managers)
• Clouds for external APIs (Spotify, Tidal)
• Blue for CLI & config
• Green for core orchestration & matching
• Orange for external interactions/services
• User → CLI
• CLI → ConfigManager → AuthServer
• AuthServer → External APIs → AuthManager
• Orchestration → Services → External APIs
• Services → Matching → Services
• ProgressReporter → File system
• Data flows (tokens, playlists, track IDs)