feat: chapters API

noook · Jul 24, 2023 · b30f9a5 · b30f9a5
1 parent b375b89
commit b30f9a5
Show file tree

Hide file tree

Showing 6 changed files with 185 additions and 128 deletions.
diff --git a/src/api/chapters.ts b/src/api/chapters.ts
@@ -0,0 +1,30 @@
+import type { ChapterObject, GetChapterOptions, GetChaptersResponse } from '../types'
+import { ApiPart } from './api.part'
+
+export class ChaptersApi extends ApiPart {
+  /**
+   * Get Spotify catalog information for a single chapter.
+   *
+   * **Note:** Chapters are only available for the US, UK, Ireland, New Zealand and Australia markets.
+   *
+   * @param id The [Spotify ID](https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids) for the chapter.
+   */
+  public getChapter(id: string, opts: GetChapterOptions = {}): Promise<ChapterObject> {
+    return this.$fetch<ChapterObject>(`/chapters/${id}`, {
+      query: opts,
+    })
+  }
+
+  /**
+   * Get Spotify catalog information for several chapters identified by their Spotify IDs.
+   * @param ids A list of the [Spotify IDs](https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids).
+   */
+  public getChapters(ids: string[], opts: GetChapterOptions = {}): Promise<GetChaptersResponse> {
+    return this.$fetch<GetChaptersResponse>('/chapters', {
+      query: {
+        ids: ids.join(','),
+        ...opts,
+      },
+    })
+  }
+}
diff --git a/src/api/client.ts b/src/api/client.ts
@@ -1,6 +1,6 @@
 import type { $Fetch } from 'ofetch'
 import { Headers, ofetch } from 'ofetch'
-import { AlbumsApi, ArtistsApi, AudiobooksApi, CategoriesApi, GenresApi, MarketsApi, PlayerApi, PlaylistsApi, SearchApi, UsersApi } from '.'
+import { AlbumsApi, ArtistsApi, AudiobooksApi, CategoriesApi, ChaptersApi, GenresApi, MarketsApi, PlayerApi, PlaylistsApi, SearchApi, UsersApi } from '.'
 
 export class SpotifyClient {
   private token: null | string = null
@@ -22,6 +22,7 @@ export class SpotifyClient {
     this.artists = new ArtistsApi(this.$fetch)
     this.audiobooks = new AudiobooksApi(this.$fetch)
     this.categories = new CategoriesApi(this.$fetch)
+    this.chapters = new ChaptersApi(this.$fetch)
     this.genres = new GenresApi(this.$fetch)
     this.markets = new MarketsApi(this.$fetch)
     this.player = new PlayerApi(this.$fetch)
@@ -44,6 +45,8 @@ export class SpotifyClient {
 
   public categories: CategoriesApi
 
+  public chapters: ChaptersApi
+
   public genres: GenresApi
 
   public markets: MarketsApi

diff --git a/src/api/index.ts b/src/api/index.ts
@@ -2,6 +2,7 @@ export * from './albums'
 export * from './artists'
 export * from './audiobooks'
 export * from './categories'
+export * from './chapters'
 export * from './genres'
 export * from './markets'
 export * from './player'

diff --git a/src/types/audiobook.ts b/src/types/audiobook.ts
@@ -1,4 +1,5 @@
 import type { CopyrightsObject, ExternalUrlObject, ImageObject, Market, PaginatedResults, PaginationQueryOptions } from './common'
+import type { SimplifiedChapterObject } from '.'
 
 export interface GetAudiobookOptions {
 /**
@@ -28,133 +29,6 @@ export interface AudiobookNarrator {
   name: string
 }
 
-export interface SimplifiedChapterObject {
-  /**
-   * A URL to a 30 second preview (MP3 format) of the episode. null if not available.
-   */
-  audio_preview_url: string | null
-
-  /**
-   * /**
-   * A list of the countries in which the track can be played, identified by their
-   * [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code.
-   */
-  available_markets: string[]
-
-  /**
-   * The number of the chapter
-   */
-  chapter_number: number
-
-  /**
-   * A description of the audiobook. HTML tags are stripped away from this field, use `html_description` field in case HTML tags are needed.
-   */
-  description: string
-
-  /**
-   * A description of the audiobook. This field may contain HTML tags.
-   */
-  html_description: string
-
-  /**
-   * The episode length in milliseconds.
-   */
-  duration_ms: number
-
-  /**
-   * Whether or not the audiobook has explicit content (`true` = yes it does; `false` = no it does not OR unknown).
-   */
-  explicit: boolean
-
-  /**
-   * External URLs for this episode.
-   */
-  external_urls: ExternalUrlObject
-
-  /**
-   * A link to the Web API endpoint providing full details of the episode.
-   */
-  href: string
-
-  /**
-   * The [Spotify ID](https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids) for the episode.
-   */
-  id: string
-
-  /**
-   * he cover art for the episode in various sizes, widest first.
-   */
-  images: ImageObject[]
-
-  /**
-   * `true` if the episode is playable in the given market. Otherwise `false`.
-   */
-  is_playable: boolean
-
-  /**
-   * A list of the languages used in the audiobook, identified by their [ISO 639](https://en.wikipedia.org/wiki/ISO_639) code.
-   */
-  languages: string[]
-
-  /**
-   * The name of the episode
-   */
-  name: string
-
-  /**
-   * The date the episode was first released, for example `"1981-12-15"`. Depending on the precision, it might be shown as `"1981"` or `"1981-12"`.
-   */
-  release_date: string
-
-  /**
-   * The precision with which `release_date` value is known.
-   */
-  release_date_precision: 'year' | 'month' | 'day'
-
-  /**
-   * The user's most recent position in the episode. Set if the supplied access token is a user token and has the scope 'user-read-playback-position'.
-   */
-  resume_point?: {
-    /**
-     * Whether or not the episode has been fully played by the user.
-     */
-    fully_played: boolean
-
-    /**
-     * The user's most recent position in the episode in milliseconds.
-     */
-    resume_position_ms: number
-  }
-
-  /**
-   * The object type.
-   */
-  type: 'episode'
-
-  /**
-   * The [Spotify URI](https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids) for the episode.
-   */
-  uri: string
-
-  /**
-   * Included in the response when a content restriction is applied.
-   */
-  restrictions?: {
-    /**
-     * The reason for the restriction. Supported values:
-     * - `market` - The content item is not available in the given market.
-     * - `product` - The content item is not available for the user's subscription type.
-     * - `explicit` - The content item is explicit and the user's account is set to not play explicit content.
-     * - `payment_required` - Payment is required to play the content item.
-     *
-     * Additional reasons may be added in the future.
-     *
-     * **Note:** If you use this field, make sure that your application safely handles unknown values.
-     */
-    reason: string
-  }
-}
-
 export interface AudiobookObject {
   authors: AudiobookAuthor[]
 

diff --git a/src/types/chapters.ts b/src/types/chapters.ts
@@ -0,0 +1,148 @@
+import type { ExternalUrlObject, ImageObject, Market } from './common'
+import type { SimplifiedAudiobookObject } from '.'
+
+export interface GetChapterOptions {
+  /**
+   * An [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. If a country code is specified,
+   * only content that is available in that market will be returned.
+   */
+  market?: Market
+}
+
+export interface ChapterObject {
+  /**
+   * A URL to a 30 second preview (MP3 format) of the episode. null if not available.
+   */
+  audio_preview_url: string | null
+
+  /**
+   * /**
+   * A list of the countries in which the track can be played, identified by their
+   * [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code.
+   */
+  available_markets: string[]
+
+  /**
+   * The number of the chapter
+   */
+  chapter_number: number
+
+  /**
+   * A description of the audiobook. HTML tags are stripped away from this field, use `html_description` field in case HTML tags are needed.
+   */
+  description: string
+
+  /**
+   * A description of the audiobook. This field may contain HTML tags.
+   */
+  html_description: string
+
+  /**
+   * The episode length in milliseconds.
+   */
+  duration_ms: number
+
+  /**
+   * Whether or not the audiobook has explicit content (`true` = yes it does; `false` = no it does not OR unknown).
+   */
+  explicit: boolean
+
+  /**
+   * External URLs for this episode.
+   */
+  external_urls: ExternalUrlObject
+
+  /**
+   * A link to the Web API endpoint providing full details of the episode.
+   */
+  href: string
+
+  /**
+   * The [Spotify ID](https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids) for the episode.
+   */
+  id: string
+
+  /**
+   * he cover art for the episode in various sizes, widest first.
+   */
+  images: ImageObject[]
+
+  /**
+   * `true` if the episode is playable in the given market. Otherwise `false`.
+   */
+  is_playable: boolean
+
+  /**
+   * A list of the languages used in the audiobook, identified by their [ISO 639](https://en.wikipedia.org/wiki/ISO_639) code.
+   */
+  languages: string[]
+
+  /**
+   * The name of the episode
+   */
+  name: string
+
+  /**
+   * The date the episode was first released, for example `"1981-12-15"`. Depending on the precision, it might be shown as `"1981"` or `"1981-12"`.
+   */
+  release_date: string
+
+  /**
+   * The precision with which `release_date` value is known.
+   */
+  release_date_precision: 'year' | 'month' | 'day'
+
+  /**
+   * The user's most recent position in the episode. Set if the supplied access token is a user token and has the scope 'user-read-playback-position'.
+   */
+  resume_point?: {
+    /**
+     * Whether or not the episode has been fully played by the user.
+     */
+    fully_played: boolean
+
+    /**
+     * The user's most recent position in the episode in milliseconds.
+     */
+    resume_position_ms: number
+  }
+
+  /**
+   * The object type.
+   */
+  type: 'episode'
+
+  /**
+   * The [Spotify URI](https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids) for the episode.
+   */
+  uri: string
+
+  /**
+   * Included in the response when a content restriction is applied.
+   */
+  restrictions?: {
+    /**
+     * The reason for the restriction. Supported values:
+     * - `market` - The content item is not available in the given market.
+     * - `product` - The content item is not available for the user's subscription type.
+     * - `explicit` - The content item is explicit and the user's account is set to not play explicit content.
+     * - `payment_required` - Payment is required to play the content item.
+     *
+     * Additional reasons may be added in the future.
+     *
+     * **Note:** If you use this field, make sure that your application safely handles unknown values.
+     */
+    reason: string
+  }
+
+  /**
+   * The audiobook for which the chapter belongs.
+   */
+  audiobook: SimplifiedAudiobookObject
+}
+
+export type SimplifiedChapterObject = Omit<ChapterObject, 'audiobook'>
+
+export interface GetChaptersResponse {
+  chapters: ChapterObject[]
+}
diff --git a/src/types/index.ts b/src/types/index.ts
@@ -3,6 +3,7 @@ export * from './artist'
 export * from './album'
 export * from './audiobook'
 export * from './categories'
+export * from './chapters'
 export * from './episode'
 export * from './markets'
 export * from './player'