feat: categories API

src/api/categories.ts

@@ -0,0 +1,16 @@
+import type { CategoryItem, GetCategoriesOptions, GetCategoriesResults } from '../types'
+import { ApiPart } from './api.part'
+
+export class CategoriesApi extends ApiPart {
+  public async getCategories(opts: GetCategoriesOptions = {}): Promise<GetCategoriesResults> {
+    return this.$fetch<GetCategoriesResults>('/browse/categories', {
+      query: opts,
+    })
+  }
+
+  public async getCategory(id: string, opts: Pick<GetCategoriesOptions, 'country' | 'locale'> = {}): Promise<CategoryItem> {
+    return this.$fetch<CategoryItem>(`/browse/categories/${id}`, {
+      query: opts,
+    })
+  }
+}

src/api/client.ts

@@ -1,6 +1,6 @@
 import type { $Fetch } from 'ofetch'
 import { Headers, ofetch } from 'ofetch'
-import { AlbumsApi, ArtistsApi, GenresApi, PlayerApi, PlaylistsApi, SearchApi, UsersApi } from '.'
+import { AlbumsApi, ArtistsApi, CategoriesApi, GenresApi, PlayerApi, PlaylistsApi, SearchApi, UsersApi } from '.'
 
 export class SpotifyClient {
   private token: null | string = null
@@ -20,6 +20,7 @@ export class SpotifyClient {
 
     this.albums = new AlbumsApi(this.$fetch)
     this.artists = new ArtistsApi(this.$fetch)
+    this.categories = new CategoriesApi(this.$fetch)
     this.genres = new GenresApi(this.$fetch)
     this.player = new PlayerApi(this.$fetch)
     this.playlists = new PlaylistsApi(this.$fetch)
@@ -37,6 +38,8 @@ export class SpotifyClient {
 
   public artists: ArtistsApi
 
+  public categories: CategoriesApi
+
   public genres: GenresApi
 
   public player: PlayerApi

src/api/index.ts

@@ -1,5 +1,6 @@
 export * from './albums'
 export * from './artists'
+export * from './categories'
 export * from './genres'
 export * from './player'
 export * from './playlists'

src/types/categories.ts

@@ -0,0 +1,63 @@
+import type { ImageObject, PaginatedResults } from './common'
+
+export interface GetCategoriesOptions {
+  /**
+   * A country: an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.
+   * Provide this parameter if you want the list of returned items to be relevant to a particular country.
+   * If omitted, the returned items will be relevant to all countries.
+   */
+  country?: string
+
+  /**
+   * The desired language, consisting of a lowercase [ISO 639-1 ](https://en.wikipedia.org/wiki/ISO_639-1) language code
+   * and an uppercase [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/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 results returned in a particular language (where available).
+   *
+   * **Note:** if locale is not supplied, or if the specified language is not available, all strings will be returned in
+   * the Spotify default language (American English).
+   *
+   * The locale parameter, combined with the country parameter, may give odd results if not carefully matched.For example country=SE&locale=de_DE will return a list of categories relevant to Sweden but as German language strings.
+   */
+  locale?: string
+
+  /**
+   * The maximum number of items to return.
+   * @default 20
+   * @max `50`
+   */
+  limit?: number
+
+  /**
+   * The index of the first item to return. Use with limit to get the next set of items.
+   * @default 0
+   */
+  offset?: number
+}
+
+export interface CategoryItem {
+  /**
+   * A link to the Web API endpoint returning full details of the category.
+   */
+  href: string
+
+  /**
+   * The category icon, in various sizes.
+   */
+  icons: ImageObject[]
+
+  /**
+   * The Spotify [category ID](https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids) of the category.
+   */
+  id: string
+
+  /**
+   * The name of the category.
+   */
+  name: string
+}
+
+export interface GetCategoriesResults {
+  categories: PaginatedResults<CategoryItem>
+}

src/types/index.ts

@@ -1,6 +1,7 @@
 export * from './common'
 export * from './artist'
 export * from './album'
+export * from './categories'
 export * from './episode'
 export * from './player'
 export * from './playlist'