SoundCloud API Integration

import { soundCloudApi } from '@/server/services/soundcloud';

// Access methods via organized structure
const tracks = await soundCloudApi.tracks.getFromUser('username');
const userInfo = await soundCloudApi.users.getInfo('username');

export const soundCloudApi = {
  tracks: {
    getFromUser: getUserTracks,
  },
  users: {
    getInfo: getUserInfo,
  },
};

async function getSoundCloudToken(): Promise<string>

interface SoundCloudToken {
  access_token: string;    // OAuth2 access token
  expires_in: number;      // Token lifetime in seconds
  token_type: string;      // "Bearer"
  scope: string;           // Granted permission scopes
}

try {
  const token = await getSoundCloudToken();
} catch (error) {
  // Throws: "Fallo en la autenticación de SoundCloud"
}

async function getUserInfo(
  user: string | number
): Promise<SoundCloudUser | null>

interface SoundCloudUser {
  id: number;                  // Unique user ID
  username: string;            // Display username
  permalink: string;           // URL-safe username
  uri: string;                 // API URI
  avatar_url: string;          // Profile picture URL
  city: string | null;         // User location city
  country: string | null;      // User location country
  followers_count: number;     // Number of followers
  followings_count: number;    // Number of users followed
  track_count: number;         // Total tracks uploaded
  [key: string]: any;          // Additional API fields
}

GET https://api.soundcloud.com/resolve?url=https://soundcloud.com/{username}

import { getUserInfo } from '@/server/services/soundcloud/users';

// By username
const user = await getUserInfo('jowymusic');
if (user) {
  console.log(`${user.username} (ID: ${user.id})`);
  console.log(`Followers: ${user.followers_count}`);
  console.log(`Tracks: ${user.track_count}`);
}

// By user ID
const userById = await getUserInfo(12345678);

async function getUserTracks(
  user: string | number,
  limit = 10,
  offset = 0
): Promise<SoundCloudTrack[] | null>

interface SoundCloudTrack {
  kind: "track";               // Resource type identifier
  id: number;                  // Unique track ID
  urn: string;                 // Uniform Resource Name
  created_at: string;          // ISO 8601 timestamp
  duration: number;            // Track duration in milliseconds
  title: string;               // Track title
  description: string | null;  // Track description
  genre: string;               // Genre classification
  tag_list: string;            // Space-separated tags
  permalink_url: string;       // Public track URL
  artwork_url: string | null;  // Cover art image URL
  stream_url: string;          // Streaming endpoint
  waveform_url: string;        // Waveform visualization URL
  user: SoundCloudUser;        // Track creator information
  playback_count: number;      // Total plays
  download_count: number;      // Total downloads
  favoritings_count: number;   // Total favorites/likes
  comment_count: number;       // Total comments
  streamable: boolean;         // Streaming availability
  downloadable: boolean;       // Download availability
  [key: string]: any;          // Additional API fields
}

GET https://api.soundcloud.com/users/{user_id}/tracks?limit={limit}&offset={offset}

import { getUserTracks } from '@/server/services/soundcloud/tracks';

// Get first 10 tracks
const tracks = await getUserTracks('jowymusic', 10, 0);

if (tracks) {
  tracks.forEach(track => {
    console.log(`${track.title} by ${track.user.username}`);
    console.log(`Plays: ${track.playback_count}`);
    console.log(`Duration: ${track.duration}ms`);
    console.log(`URL: ${track.permalink_url}`);
  });
}

// Pagination: Get next 10 tracks
const moreTracks = await getUserTracks('jowymusic', 10, 10);

// Get tracks by user ID
const tracksByID = await getUserTracks(12345678, 20);

const tracks = await getUserTracks('nonexistent_user');
if (!tracks) {
  console.error('Failed to retrieve tracks or user not found');
}