Add support for Chapters endpoints

Author: JohnnyCrazy

SpotifyAPI.Web/Clients/ChaptersClient.cs

@@ -0,0 +1,34 @@
+using System.Threading;
+using System.Threading.Tasks;
+using SpotifyAPI.Web.Http;
+using URLs = SpotifyAPI.Web.SpotifyUrls;
+
+namespace SpotifyAPI.Web
+{
+  public class ChaptersClient : APIClient, IChaptersClient
+  {
+    public ChaptersClient(IAPIConnector apiConnector) : base(apiConnector) { }
+
+    public Task<FullAudiobookChapter> Get(string chapterId, CancellationToken cancel = default)
+    {
+      Ensure.ArgumentNotNullOrEmptyString(chapterId, nameof(chapterId));
+
+      return API.Get<FullAudiobookChapter>(URLs.Chapter(chapterId), cancel);
+    }
+
+    public Task<FullAudiobookChapter> Get(string chapterId, ChapterRequest request, CancellationToken cancel = default)
+    {
+      Ensure.ArgumentNotNullOrEmptyString(chapterId, nameof(chapterId));
+      Ensure.ArgumentNotNull(request, nameof(request));
+
+      return API.Get<FullAudiobookChapter>(URLs.Chapter(chapterId), request.BuildQueryParams(), cancel);
+    }
+
+    public Task<ChaptersResponse> GetSeveral(ChaptersRequest request, CancellationToken cancel = default)
+    {
+      Ensure.ArgumentNotNull(request, nameof(request));
+
+      return API.Get<ChaptersResponse>(URLs.Chapters(), request.BuildQueryParams(), cancel);
+    }
+  }
+}

SpotifyAPI.Web/Clients/Interfaces/IChaptersClient.cs

@@ -0,0 +1,47 @@
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace SpotifyAPI.Web
+{
+  /// <summary>
+  /// Endpoints for retrieving information about one or more chapters from the Spotify catalog.
+  /// </summary>
+  public interface IChaptersClient
+  {
+    /// <summary>
+    /// Get Spotify catalog information for a single audiobook chapter. Chapters are only available within the US, UK, Canada, Ireland, New Zealand and Australia markets.
+    /// </summary>
+    /// <param name="chapterId">The Spotify ID for the chapter.</param>
+    /// <param name="cancel">The cancellation-token to allow to cancel the request.</param>
+    /// <remarks>
+    /// https://developer.spotify.com/documentation/web-api/reference/get-a-chapter
+    /// </remarks>
+    /// <returns></returns>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1716")]
+    Task<FullAudiobookChapter> Get(string chapterId, CancellationToken cancel = default);
+
+    /// <summary>
+    /// Get Spotify catalog information for a single audiobook chapter. Chapters are only available within the US, UK, Canada, Ireland, New Zealand and Australia markets.
+    /// </summary>
+    /// <param name="chapterId">The Spotify ID for the chapter.</param>
+    /// <param name="request">The request-model which contains required and optional parameters.</param>
+    /// <param name="cancel">The cancellation-token to allow to cancel the request.</param>
+    /// <remarks>
+    /// https://developer.spotify.com/documentation/web-api/reference/get-a-chapter
+    /// </remarks>
+    /// <returns></returns>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1716")]
+    Task<FullAudiobookChapter> Get(string chapterId, ChapterRequest request, CancellationToken cancel = default);
+
+    /// <summary>
+    /// Get Spotify catalog information for several audiobook chapters identified by their Spotify IDs. Chapters are only available within the US, UK, Canada, Ireland, New Zealand and Australia markets.
+    /// </summary>
+    /// <param name="request">The request-model which contains required and optional parameters.</param>
+    /// <param name="cancel">The cancellation-token to allow to cancel the request.</param>
+    /// <remarks>
+    /// https://developer.spotify.com/documentation/web-api/reference/get-several-chapters
+    /// </remarks>
+    /// <returns></returns>
+    Task<ChaptersResponse> GetSeveral(ChaptersRequest request, CancellationToken cancel = default);
+  }
+}

SpotifyAPI.Web/Clients/Interfaces/ISpotifyClient.cs

@@ -98,6 +98,12 @@ public interface ISpotifyClient
     /// <value></value>
     IAudiobooksClient Audiobooks { get; }
 
+    /// <summary>
+    /// Operations related to Spotify Audiobook Chapters
+    /// </summary>
+    /// <value></value>
+    IChaptersClient Chapters { get; }
+
     /// <summary>
     /// Returns the last response received by an API call.
     /// </summary>

SpotifyAPI.Web/Clients/SpotifyClient.cs

@@ -53,6 +53,7 @@ public SpotifyClient(SpotifyClientConfig config)
       Library = new LibraryClient(_apiConnector);
       Markets = new MarketsClient(_apiConnector);
       Audiobooks = new AudiobooksClient(_apiConnector);
+      Chapters = new ChaptersClient(_apiConnector);
     }
 
     public IPaginator DefaultPaginator { get; }
@@ -87,6 +88,8 @@ public SpotifyClient(SpotifyClientConfig config)
 
     public IAudiobooksClient Audiobooks { get; }
 
+    public IChaptersClient Chapters { get; }
+
     public IResponse? LastResponse { get; private set; }
 
     /// <summary>

SpotifyAPI.Web/Models/Request/ChapterRequest.cs

@@ -0,0 +1,23 @@
+namespace SpotifyAPI.Web
+{
+  public class ChapterRequest : RequestParams
+  {
+    /// <summary>
+    /// The market you’d like to request. Synonym for country.
+    /// </summary>
+    /// <value></value>
+    [QueryParam("market")]
+    public string? Market { get; set; }
+
+    /// <summary>
+    /// The desired language, consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code,
+    /// joined by an underscore. For example: es_MX, meaning "Spanish (Mexico)".
+    /// Provide this parameter if you want the category strings returned in a particular language.
+    /// Note that, if locale is not supplied, or if the specified language is not available,
+    /// the category strings returned will be in the Spotify default language (American English).
+    /// </summary>
+    /// <value></value>
+    [QueryParam("locale")]
+    public string? Locale { get; set; }
+  }
+}

SpotifyAPI.Web/Models/Request/ChaptersRequest.cs

@@ -0,0 +1,45 @@
+using System.Collections.Generic;
+
+namespace SpotifyAPI.Web
+{
+  public class ChaptersRequest : RequestParams
+  {
+    /// <summary>
+    /// ChaptersRequest
+    /// </summary>
+    /// <param name="ids">A comma-separated list of the Spotify IDs for the chapters. Maximum: 50 IDs.</param>
+    public ChaptersRequest(IList<string> ids)
+    {
+      Ensure.ArgumentNotNullOrEmptyList(ids, nameof(ids));
+
+      Ids = ids;
+    }
+
+    /// <summary>
+    /// A comma-separated list of the Spotify IDs for the chapters. Maximum: 20 IDs.
+    /// </summary>
+    /// <value></value>
+    [QueryParam("ids")]
+    public IList<string> Ids { get; }
+
+    /// <summary>
+    /// An ISO 3166-1 alpha-2 country code or the string from_token.
+    /// Provide this parameter if you want to apply Track Relinking.
+    /// </summary>
+    /// <value></value>
+    [QueryParam("market")]
+    public string? Market { get; set; }
+
+    /// <summary>
+    /// The desired language, consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code,
+    /// joined by an underscore. For example: es_MX, meaning "Spanish (Mexico)".
+    /// Provide this parameter if you want the category strings returned in a particular language.
+    /// Note that, if locale is not supplied, or if the specified language is not available,
+    /// the category strings returned will be in the Spotify default language (American English).
+    /// </summary>
+    /// <value></value>
+    [QueryParam("locale")]
+    public string? Locale { get; set; }
+  }
+}
+

SpotifyAPI.Web/Models/Response/ChaptersResponse.cs

@@ -0,0 +1,10 @@
+using System.Collections.Generic;
+
+namespace SpotifyAPI.Web
+{
+  public class ChaptersResponse
+  {
+    public List<FullAudiobookChapter> Chapters { get; set; } = default!;
+  }
+}
+

SpotifyAPI.Web/Models/Response/FullAudiobookChapter.cs

@@ -0,0 +1,7 @@
+namespace SpotifyAPI.Web
+{
+  public class FullAudiobookChapter : SimpleAudiobookChapter
+  {
+    public SimpleAudiobook Audiobook { get; set; } = default!;
+  }
+}

SpotifyAPI.Web/SpotifyUrls.cs

@@ -145,6 +145,10 @@ public static class SpotifyUrls
 
     public static Uri AudiobookChapters(string audiobookId) => EUri($"audiobooks/{audiobookId}/chapters");
 
+    public static Uri Chapters() => EUri($"chapters");
+
+    public static Uri Chapter(string chapterId) => EUri($"chapters/${chapterId}");
+
     private static Uri EUri(FormattableString path) => new(path.ToString(_provider), UriKind.Relative);
   }
 }