Skip to content

Commit 034b049

Browse files
jerry6251jerry6251
committed
Add client interfaces
Closes #9
1 parent a65af2f commit 034b049

File tree

10 files changed

+591
-174
lines changed

10 files changed

+591
-174
lines changed

‎SoundCloudExplode/ISoundCloudClient.cs‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
using System;
2+
using System.Collections.Generic;
3+
using System.Threading;
4+
using System.Threading.Tasks;
5+
using SoundCloudExplode.Common;
6+
using SoundCloudExplode.Playlists;
7+
using SoundCloudExplode.Search;
8+
using SoundCloudExplode.Tracks;
9+
using SoundCloudExplode.Users;
10+
11+
namespace SoundCloudExplode;
12+
13+
/// <summary>
14+
/// Interface for SoundCloud client operations.
15+
/// </summary>
16+
public interface ISoundCloudClient
17+
{
18+
/// <summary>
19+
/// Gets a value indicating whether the client is initialized.
20+
/// </summary>
21+
bool IsInitialized { get; }
22+
23+
/// <summary>
24+
/// Operations related to Soundcloud search.
25+
/// </summary>
26+
ISearchClient Search { get; }
27+
28+
/// <summary>
29+
/// Operations related to Soundcloud tracks.
30+
/// </summary>
31+
ITrackClient Tracks { get; }
32+
33+
/// <summary>
34+
/// Operations related to Soundcloud playlists/albums.
35+
/// </summary>
36+
IPlaylistClient Playlists { get; }
37+
38+
/// <summary>
39+
/// Operations related to Soundcloud users.
40+
/// </summary>
41+
IUserClient Users { get; }
42+
43+
/// <summary>
44+
/// Initializes the client asynchronously.
45+
/// </summary>
46+
Task InitializeAsync(CancellationToken cancellationToken = default);
47+
48+
/// <summary>
49+
/// Gets the client ID.
50+
/// </summary>
51+
Task<string> GetClientIdAsync(CancellationToken cancellationToken = default);
52+
53+
/// <summary>
54+
/// Gets the kind of a SoundCloud URL.
55+
/// </summary>
56+
Task<Kind> GetUrlKindAsync(string url, CancellationToken cancellationToken = default);
57+
58+
/// <summary>
59+
/// Downloads a track to a file path.
60+
/// </summary>
61+
ValueTask DownloadAsync(
62+
Track track,
63+
string filePath,
64+
IProgress<double>? progress = null,
65+
Dictionary<string, string>? headers = null,
66+
CancellationToken cancellationToken = default
67+
);
68+
}

‎SoundCloudExplode/Playlists/IPlaylistClient.cs‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
using System.Collections.Generic;
2+
using System.Threading;
3+
using System.Threading.Tasks;
4+
using SoundCloudExplode.Common;
5+
using SoundCloudExplode.Tracks;
6+
7+
namespace SoundCloudExplode.Playlists;
8+
9+
/// <summary>
10+
/// Defines the functionality for SoundCloud playlist/album operations.
11+
/// </summary>
12+
public interface IPlaylistClient
13+
{
14+
/// <summary>
15+
/// Checks for a valid playlist URL.
16+
/// </summary>
17+
/// <param name="url">The URL to validate.</param>
18+
/// <param name="cancellationToken">A cancellation token.</param>
19+
Task<bool> IsUrlValidAsync(string url, CancellationToken cancellationToken = default);
20+
21+
/// <summary>
22+
/// Gets the metadata for a playlist.
23+
/// </summary>
24+
/// <param name="url">The playlist URL.</param>
25+
/// <param name="populateAllTracks">
26+
/// Set to true to populate all tracks in the playlist.
27+
/// If false, only the tracks id and playlist info will return.
28+
/// </param>
29+
/// <param name="cancellationToken">A cancellation token.</param>
30+
ValueTask<Playlist> GetAsync(
31+
string url,
32+
bool populateAllTracks = false,
33+
CancellationToken cancellationToken = default
34+
);
35+
36+
/// <summary>
37+
/// Enumerates batches of tracks in a playlist.
38+
/// </summary>
39+
/// <param name="url">The playlist URL.</param>
40+
/// <param name="offset">The offset for pagination.</param>
41+
/// <param name="limit">The limit for the number of results.</param>
42+
/// <param name="cancellationToken">A cancellation token.</param>
43+
IAsyncEnumerable<Batch<Track>> GetTrackBatchesAsync(
44+
string url,
45+
int offset = Constants.DefaultOffset,
46+
int limit = Constants.DefaultLimit,
47+
CancellationToken cancellationToken = default
48+
);
49+
50+
/// <summary>
51+
/// Enumerates all tracks in a playlist.
52+
/// </summary>
53+
/// <param name="url">The playlist URL.</param>
54+
/// <param name="offset">The offset for pagination.</param>
55+
/// <param name="limit">The limit for the number of results.</param>
56+
/// <param name="cancellationToken">A cancellation token.</param>
57+
IAsyncEnumerable<Track> GetTracksAsync(
58+
string url,
59+
int offset = Constants.DefaultOffset,
60+
int limit = Constants.DefaultLimit,
61+
CancellationToken cancellationToken = default
62+
);
63+
64+
/// <summary>
65+
/// Enumerates all tracks in a playlist.
66+
/// </summary>
67+
/// <param name="url">The playlist URL.</param>
68+
/// <param name="cancellationToken">A cancellation token.</param>
69+
IAsyncEnumerable<Track> GetTracksAsync(string url, CancellationToken cancellationToken);
70+
}

‎SoundCloudExplode/Playlists/PlaylistClient.cs‎

Lines changed: 6 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,12 @@ namespace SoundCloudExplode.Playlists;
2222
/// <remarks>
2323
/// Initializes an instance of <see cref="PlaylistClient"/>.
2424
/// </remarks>
25-
public class PlaylistClient(HttpClient http, SoundcloudEndpoint endpoint)
25+
public class PlaylistClient(HttpClient http, SoundcloudEndpoint endpoint) : IPlaylistClient
2626
{
2727
private readonly Regex ShortUrlRegex = new(@"on\.soundcloud\..+?\/.+?");
2828
private readonly Regex PlaylistRegex = new(@"soundcloud\..+?\/(.*?)\/sets\/(.*?)(?:&|/|$)");
2929

30-
/// <summary>
31-
/// Checks for valid playlist url.
32-
/// </summary>
33-
/// <exception cref="SoundcloudExplodeException"/>
30+
/// <inheritdoc />
3431
public async Task<bool> IsUrlValidAsync(
3532
string url,
3633
CancellationToken cancellationToken = default
@@ -56,15 +53,7 @@ public async Task<bool> IsUrlValidAsync(
5653
return PlaylistRegex.IsMatch(url);
5754
}
5855

59-
/// <summary>
60-
/// Gets the metadata associated with the specified playlist.
61-
/// </summary>
62-
/// <param name="url"></param>
63-
/// <param name="populateAllTracks">Set to true if you want to populate all tracks in playlist.
64-
/// information at the same time. If false, only the tracks id and playlist info will return.
65-
/// </param>
66-
/// <param name="cancellationToken"></param>
67-
/// <exception cref="SoundcloudExplodeException"/>
56+
/// <inheritdoc />
6857
public async ValueTask<Playlist> GetAsync(
6958
string url,
7059
bool populateAllTracks = false,
@@ -92,10 +81,7 @@ public async ValueTask<Playlist> GetAsync(
9281
return playlist;
9382
}
9483

95-
/// <summary>
96-
/// Enumerates tracks included in the specified playlist url.
97-
/// </summary>
98-
/// <exception cref="SoundcloudExplodeException"/>
84+
/// <inheritdoc />
9985
public async IAsyncEnumerable<Batch<Track>> GetTrackBatchesAsync(
10086
string url,
10187
int offset = Constants.DefaultOffset,
@@ -139,21 +125,15 @@ public async IAsyncEnumerable<Batch<Track>> GetTrackBatchesAsync(
139125
}
140126
}
141127

142-
/// <summary>
143-
/// Enumerates tracks included in the specified playlist url.
144-
/// </summary>
145-
/// <exception cref="SoundcloudExplodeException"/>
128+
/// <inheritdoc />
146129
public IAsyncEnumerable<Track> GetTracksAsync(
147130
string url,
148131
int offset = Constants.DefaultOffset,
149132
int limit = Constants.DefaultLimit,
150133
CancellationToken cancellationToken = default
151134
) => GetTrackBatchesAsync(url, offset, limit, cancellationToken).FlattenAsync();
152135

153-
/// <summary>
154-
/// Enumerates tracks included in the specified playlist url.
155-
/// </summary>
156-
/// <exception cref="SoundcloudExplodeException"/>
136+
/// <inheritdoc />
157137
public IAsyncEnumerable<Track> GetTracksAsync(
158138
string url,
159139
CancellationToken cancellationToken

‎SoundCloudExplode/Search/ISearchClient.cs‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
using System.Collections.Generic;
2+
using System.Threading;
3+
using System.Threading.Tasks;
4+
using SoundCloudExplode.Common;
5+
using SoundCloudExplode.Exceptions;
6+
7+
namespace SoundCloudExplode.Search;
8+
9+
/// <summary>
10+
/// Provides functionality to search SoundCloud for tracks, playlists, albums, and users.
11+
/// </summary>
12+
public interface ISearchClient
13+
{
14+
/// <summary>
15+
/// Checks if a given URL is a well-formed SoundCloud URL.
16+
/// </summary>
17+
/// <param name="url">The URL to validate.</param>
18+
/// <returns>True if the URL is valid; otherwise, false.</returns>
19+
/// <exception cref="SoundcloudExplodeException"/>
20+
bool IsUrlValid(string url);
21+
22+
/// <summary>
23+
/// Gets a list of suggested search queries related to the specified query.
24+
/// </summary>
25+
/// <param name="query">The query string.</param>
26+
/// <param name="offset">The offset of results (pagination).</param>
27+
/// <param name="limit">The maximum number of results to return.</param>
28+
/// <param name="cancellationToken">Cancellation token.</param>
29+
/// <returns>A list of suggested search queries.</returns>
30+
/// <exception cref="SoundcloudExplodeException"/>
31+
ValueTask<List<string>> GetSearchQueriesAsync(
32+
string query,
33+
int offset = Constants.DefaultOffset,
34+
int limit = Constants.DefaultLimit,
35+
CancellationToken cancellationToken = default
36+
);
37+
38+
/// <summary>
39+
/// Enumerates batches of search results by query and filter type.
40+
/// </summary>
41+
/// <param name="searchQuery">The search query.</param>
42+
/// <param name="searchFilter">The type of search filter (track, user, playlist, etc.).</param>
43+
/// <param name="offset">The offset of results (pagination).</param>
44+
/// <param name="limit">The maximum number of results per batch.</param>
45+
/// <param name="cancellationToken">Cancellation token.</param>
46+
/// <returns>Async enumerable of result batches.</returns>
47+
/// <exception cref="SoundcloudExplodeException"/>
48+
IAsyncEnumerable<Batch<ISearchResult>> GetResultBatchesAsync(
49+
string searchQuery,
50+
SearchFilter searchFilter,
51+
int offset = Constants.DefaultOffset,
52+
int limit = Constants.DefaultLimit,
53+
CancellationToken cancellationToken = default
54+
);
55+
56+
/// <summary>
57+
/// Enumerates all search results by query without a specific filter.
58+
/// </summary>
59+
/// <param name="searchQuery">The search query.</param>
60+
/// <param name="offset">Offset for pagination.</param>
61+
/// <param name="limit">Limit for pagination.</param>
62+
/// <param name="cancellationToken">Cancellation token.</param>
63+
/// <returns>Async enumerable of raw search results.</returns>
64+
/// <exception cref="SoundcloudExplodeException"/>
65+
IAsyncEnumerable<ISearchResult> GetResultsAsync(
66+
string searchQuery,
67+
int offset = Constants.DefaultOffset,
68+
int limit = Constants.DefaultLimit,
69+
CancellationToken cancellationToken = default
70+
);
71+
72+
/// <summary>
73+
/// Gets track search results for the specified query.
74+
/// </summary>
75+
/// <param name="searchQuery">The search query.</param>
76+
/// <param name="offset">Offset for pagination.</param>
77+
/// <param name="limit">Limit for pagination.</param>
78+
/// <param name="cancellationToken">Cancellation token.</param>
79+
/// <returns>Async enumerable of <see cref="TrackSearchResult"/> objects.</returns>
80+
/// <exception cref="SoundcloudExplodeException"/>
81+
IAsyncEnumerable<TrackSearchResult> GetTracksAsync(
82+
string searchQuery,
83+
int offset = Constants.DefaultOffset,
84+
int limit = Constants.DefaultLimit,
85+
CancellationToken cancellationToken = default
86+
);
87+
88+
/// <summary>
89+
/// Gets playlist search results for the specified query.
90+
/// </summary>
91+
/// <param name="searchQuery">The search query.</param>
92+
/// <param name="offset">Offset for pagination.</param>
93+
/// <param name="limit">Limit for pagination.</param>
94+
/// <param name="cancellationToken">Cancellation token.</param>
95+
/// <returns>Async enumerable of <see cref="PlaylistSearchResult"/> objects.</returns>
96+
/// <exception cref="SoundcloudExplodeException"/>
97+
IAsyncEnumerable<PlaylistSearchResult> GetPlaylistsAsync(
98+
string searchQuery,
99+
int offset = Constants.DefaultOffset,
100+
int limit = Constants.DefaultLimit,
101+
CancellationToken cancellationToken = default
102+
);
103+
104+
/// <summary>
105+
/// Gets playlist results excluding albums for the specified query.
106+
/// </summary>
107+
/// <param name="searchQuery">The search query.</param>
108+
/// <param name="offset">Offset for pagination.</param>
109+
/// <param name="limit">Limit for pagination.</param>
110+
/// <param name="cancellationToken">Cancellation token.</param>
111+
/// <returns>Async enumerable of playlists without albums.</returns>
112+
/// <exception cref="SoundcloudExplodeException"/>
113+
IAsyncEnumerable<PlaylistSearchResult> GetPlaylistsWithoutAlbumsAsync(
114+
string searchQuery,
115+
int offset = Constants.DefaultOffset,
116+
int limit = Constants.DefaultLimit,
117+
CancellationToken cancellationToken = default
118+
);
119+
120+
/// <summary>
121+
/// Gets album search results for the specified query.
122+
/// </summary>
123+
/// <param name="searchQuery">The search query.</param>
124+
/// <param name="offset">Offset for pagination.</param>
125+
/// <param name="limit">Limit for pagination.</param>
126+
/// <param name="cancellationToken">Cancellation token.</param>
127+
/// <returns>Async enumerable of <see cref="PlaylistSearchResult"/> representing albums.</returns>
128+
/// <exception cref="SoundcloudExplodeException"/>
129+
IAsyncEnumerable<PlaylistSearchResult> GetAlbumsAsync(
130+
string searchQuery,
131+
int offset = Constants.DefaultOffset,
132+
int limit = Constants.DefaultLimit,
133+
CancellationToken cancellationToken = default
134+
);
135+
136+
/// <summary>
137+
/// Gets user search results for the specified query.
138+
/// </summary>
139+
/// <param name="searchQuery">The search query.</param>
140+
/// <param name="offset">Offset for pagination.</param>
141+
/// <param name="limit">Limit for pagination.</param>
142+
/// <param name="cancellationToken">Cancellation token.</param>
143+
/// <returns>Async enumerable of <see cref="UserSearchResult"/> objects.</returns>
144+
/// <exception cref="SoundcloudExplodeException"/>
145+
IAsyncEnumerable<UserSearchResult> GetUsersAsync(
146+
string searchQuery,
147+
int offset = Constants.DefaultOffset,
148+
int limit = Constants.DefaultLimit,
149+
CancellationToken cancellationToken = default
150+
);
151+
}

0 commit comments

Comments
 (0)