├── .gitattributes
├── LICENSE
├── README.md
├── index.js
├── package.json
├── tsconfig.json
└── typings
├── album.d.ts
├── artist.d.ts
├── audiobook.d.ts
├── browse.d.ts
├── episode.d.ts
├── global.d.ts
├── index.d.ts
├── player.d.ts
├── playlist.d.ts
├── show.d.ts
├── track.d.ts
└── user.d.ts
/.gitattributes:
--------------------------------------------------------------------------------
1 | * linguist-language=Typescript text=auto eol=lf
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2021 Spotify-Api.JS ❄
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Spotify Types
2 |
3 | **Module Documentation Reference:** https://spotify-api.js.org/apiTypes/
4 | **Spotify Object Index Reference:** https://developer.spotify.com/documentation/web-api/reference/#objects-index
5 |
6 | All the typings for the various Spotify API Object typings written in typescript. You can view the Spotify web api reference for all the objects [here](https://developer.spotify.com/documentation/web-api/reference/#objects-index).
7 |
8 | This is a typings modules made for [Spotify-api.js](https://github.com/spotify-api/spotify-api.js) v9. This can also be used separately just for typescript debugging when working with Spotify API. This package can be even used in deno using the cdn urls.
9 |
10 | ```ts
11 | import { SearchContent } from "spotify-types";
12 | import axios, { AxiosResponse } from "axios";
13 |
14 | const response: AxiosResponse = await axios.get('https://api.spotify.com/v1/search', {
15 | headers: { "Authorization": "Bearer " + process.env.SPOTIFY_TOKEN },
16 | params: {
17 | q: "search query",
18 | type: "track",
19 | market: "US"
20 | }
21 | });
22 | ```
--------------------------------------------------------------------------------
/index.js:
--------------------------------------------------------------------------------
1 | "use strict";
2 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "spotify-types",
3 | "version": "2.0.0",
4 | "description": "All the typings for the various Spotify API Object typings written in typescript.",
5 | "main": "index.js",
6 | "types": "typings/index.d.ts",
7 | "keywords": [
8 | "spotify",
9 | "spotify-api.js",
10 | "spotify-api-types",
11 | "spotify-types",
12 | "spotify-api"
13 | ],
14 | "repository": {
15 | "type": "git",
16 | "url": "https://github.com/spotify-api/spotify-types"
17 | },
18 | "scripts": {
19 | "build": "npx tsc --project tsconfig.json"
20 | },
21 | "author": "science_spot_codes",
22 | "license": "MIT"
23 | }
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "compilerOptions": {
3 | "declaration": true,
4 | "noImplicitAny": false,
5 | "strictNullChecks": true,
6 | "esModuleInterop":true,
7 | "target": "ES2018",
8 | "module": "commonjs",
9 | "allowJs": true,
10 | "moduleResolution": "node",
11 | "lib": ["es2018", "dom"],
12 | "rootDir": "./typings",
13 | "strict": true
14 | },
15 | "include": ["typings"]
16 | }
--------------------------------------------------------------------------------
/typings/album.d.ts:
--------------------------------------------------------------------------------
1 | import { Artist, SimplifiedArtist } from "./artist";
2 | import { SimplifiedTrack } from "./track";
3 | import { Copyright, ExternalID, ExternalUrl, Image, Restriction, Saved, Paging } from "./global";
4 |
5 | /**
6 | * The types of album.
7 | */
8 | export type AlbumType = 'single' | 'album' | 'compilation';
9 |
10 | /**
11 | * The groups of album.
12 | */
13 | export type AlbumGroup = AlbumType | 'appears_on';
14 |
15 | /**
16 | * The saved album object.
17 | */
18 | export type SavedAlbum = Saved<'album', Album>
19 |
20 | /**
21 | * The spotify object containing the complete details of the Spotify Album.
22 | */
23 | export interface Album extends Omit {
24 | /** The artists of the album. */
25 | artists: Artist[];
26 | /** The copyright statements of the album. */
27 | copyrights: Copyright[];
28 | /** Known external IDs for the album. */
29 | external_ids: ExternalID;
30 | /** A list of the genres used to classify the album. For example: “Prog Rock” , “Post-Grunge”. (If not yet classified, the array is empty.) */
31 | genres: string[];
32 | /** The label for the album. */
33 | label: string;
34 | /** The popularity of the album. The value will be between 0 and 100, with 100 being the most popular. The popularity is calculated from the popularity of the album’s individual tracks. */
35 | popularity: number;
36 | /** The tracks of the album. The object index says this is an array but the value returns as a Paging object so here is an union might be fixed in upcomming versions. */
37 | tracks: SimplifiedTrack[] | Paging;
38 | }
39 |
40 | /**
41 | * The spotify object containing the simplified details of the Spotify Album.
42 | */
43 | export interface SimplifiedAlbum {
44 | /** The field is present when getting an artist’s albums. */
45 | album_group?: AlbumGroup;
46 | /** The type of album. */
47 | album_type: AlbumType;
48 | /** The artists of the album. */
49 | artists: SimplifiedArtist[];
50 | /** The markets in which the album is available. */
51 | available_markets?: string[];
52 | /** Known external URLs for this album. */
53 | external_urls: ExternalUrl;
54 | /** A link to the Web API endpoint providing full details of the album. */
55 | href: string;
56 | /** The Spotify ID of the album. */
57 | id: string;
58 | /** The cover art for the album in various sizes, widest first. */
59 | images: Image[];
60 | /** The name of the album. */
61 | name: string;
62 | /** The date the album was first released, for example “1981-12-15”. */
63 | release_date: string;
64 | /** The precision with which release_date value is known: “year” , “month” , or “day”. */
65 | release_date_precision: string;
66 | /** Included in the response when a content restriction is applied. */
67 | restrictions: Restriction[];
68 | /** The total number of tracks in the album. */
69 | total_tracks: number;
70 | /** The object type which will be 'album'. */
71 | type: 'album';
72 | /** The Spotify URI for the album. */
73 | uri: string;
74 | }
--------------------------------------------------------------------------------
/typings/artist.d.ts:
--------------------------------------------------------------------------------
1 | import { ExternalUrl, Image } from "./global";
2 | import { Followers } from "./user";
3 |
4 | /**
5 | * The structure containing the simplified details of the Spotify Artist.
6 | */
7 | export interface SimplifiedArtist {
8 | /** Known external URLs for this artist. */
9 | external_urls: ExternalUrl;
10 | /** A link to the Web API endpoint providing full details of the artist. */
11 | href: string;
12 | /** The Spotify ID for the artist. */
13 | id: string;
14 | /** The name of the artist. */
15 | name: string;
16 | /** The object type: "artist". */
17 | type: 'artist';
18 | /** The Spotify URI for the artist. */
19 | uri: string;
20 | }
21 |
22 | /**
23 | * The structure containing the entire details of the Spotify Artist.
24 | */
25 | export interface Artist extends SimplifiedArtist {
26 | /** Information about the followers of the artist. */
27 | followers: Followers;
28 | /** A list of the genres the artist is associated with. For example: "Prog Rock" , "Post-Grunge". (If not yet classified, the array is empty.) */
29 | genres: string[];
30 | /** Images of the artist in various sizes, widest first. */
31 | images: Image[];
32 | /** The popularity of the artist. The value will be between 0 and 100, with 100 being the most popular. The artist’s popularity is calculated from the popularity of all the artist’s tracks. */
33 | popularity: number;
34 | }
--------------------------------------------------------------------------------
/typings/audiobook.d.ts:
--------------------------------------------------------------------------------
1 | import { ResumePoint } from "./episode";
2 | import { Copyright, ExternalUrl, Image, Paging, Restriction } from "./global";
3 |
4 | /**
5 | * The structure containing the complete details of the Spotify Audiobook.
6 | */
7 | export interface Audiobook extends SimplifiedAudiobook {
8 | /** The chapters of the audiobook. */
9 | chapters: Paging;
10 | }
11 |
12 | /**
13 | * The structure containing the complete details of the Spotify Chapter.
14 | */
15 | export interface Chapter extends SimplifiedChapter {
16 | /** The audiobook to which the chapter belongs to. */
17 | audiobook: SimplifiedAudiobook;
18 | }
19 |
20 | /**
21 | * The structure containing the simplified details of the Spotify Audiobook.
22 | */
23 | export interface SimplifiedAudiobook {
24 | /** The authors of the auidobook. */
25 | authors: Username[];
26 | /** The markets where the audiobook is available. */
27 | available_markets: string[];
28 | /** The copyright statements of the audiobook. */
29 | copyrights: Copyright[];
30 | /** The description of the audiobook. */
31 | description: string;
32 | /** The description of the audiobook with HTML tags. */
33 | html_description: string;
34 | /** The edition of the audiobook. */
35 | edition: string;
36 | /** Boolean stating if the audiobook contains explicit content. */
37 | explicit: boolean;
38 | /** The external urls of the audiobook. */
39 | external_urls: ExternalUrl;
40 | /** The href of the audiobook. */
41 | href: string;
42 | /** The ID of the audiobook. */
43 | id: string;
44 | /** All the images related to audiobook (cover arts). */
45 | images: Image[];
46 | /** The languages used in the audiobook. */
47 | languages: string[];
48 | /** The media type of the audiobook. */
49 | media_type: string;
50 | /** The name of the audiobook. */
51 | name: string;
52 | /** The narrators of the audiobook. */
53 | narrators: Username[];
54 | /** The publisher of the audiobook. */
55 | publisher: string;
56 | /** The type of the audiobook. */
57 | type: "audiobook";
58 | /** The URI of the audiobook. */
59 | uri: string;
60 | /** The total chapters of the audiobook. */
61 | total_chapters: number;
62 | }
63 |
64 | /**
65 | * The structure containing the simplified details of Spotify Chapter.
66 | */
67 | export interface SimplifiedChapter {
68 | /** The audio preview url of chapter. */
69 | audio_preview_url: string;
70 | /** The markets where the chapter is available. */
71 | available_markets: string[];
72 | /** The number of the chapter. */
73 | chapter_number: number;
74 | /** The description of the chapter. */
75 | description: string;
76 | /** The HTML description of the chapter. */
77 | html_description: string;
78 | /** The duration of the chapter in ms. */
79 | duration_ms: number;
80 | /** Boolean stating if the chapter is explicit or not. */
81 | explicit: boolean;
82 | /** The external urls of the chapter. */
83 | external_urls: ExternalUrl;
84 | /** The href of the chapter. */
85 | href: string;
86 | /** The ID of the chapter. */
87 | id: string;
88 | /** The images of the chapter. */
89 | images: Image[],
90 | /** Boolean stating if the chapter is playable or not. */
91 | is_playable: boolean;
92 | /** The languages of the chapter. */
93 | languages: string[];
94 | /** The name of the chapter. */
95 | name: string;
96 | /** 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". */
97 | release_date: string;
98 | /** The precision with which release_date value is known: "year", "month", or "day". */
99 | release_date_precision: string;
100 | /** Included in the response when a content restriction is applied. */
101 | restrictions: Restriction;
102 | /** The user’s most recent position in the chapter. Set if the supplied access token is a user token and has the scope ‘user-read-playback-position’. */
103 | resume_point?: ResumePoint;
104 | /** The Spotify object type. */
105 | type: "episode";
106 | /** The Spotify URI for the chapter. */
107 | uri: string;
108 | }
109 |
110 | /**
111 | * The structure containing the name of a particular user.
112 | */
113 | export interface Username {
114 | /** The name of the user. */
115 | name: string;
116 | }
--------------------------------------------------------------------------------
/typings/browse.d.ts:
--------------------------------------------------------------------------------
1 | import { Image } from "./global";
2 | import { SimplifiedTrack, TuneableTrack } from "./track";
3 |
4 | /**
5 | * An object containing details about the spotify category.
6 | */
7 | export interface Category {
8 | /** A link to the Web API endpoint returning full details of the category. */
9 | href: string;
10 | /** The category icon, in various sizes. */
11 | icons: Image[];
12 | /** The Spotify category ID of the category. */
13 | id: string;
14 | /** The name of the category. */
15 | name: string;
16 | }
17 |
18 | /**
19 | * The spotify recommendation seed object.
20 | */
21 | export interface RecommendationSeed {
22 | /** The number of tracks available after min_* and max_* filters have been applied. */
23 | afterFilteringSize: number;
24 | /** The number of tracks available after relinking for regional availability. */
25 | afterRelinkingSize: number;
26 | /** A link to the full track or artist data for this seed. */
27 | href: string;
28 | /** The id used to select this seed. This will be the same as the string used in the seed_artists, seed_tracks or seed_genres parameter. */
29 | id: string;
30 | /** The number of recommended tracks available for this seed. */
31 | initialPoolSize: number;
32 | /** The entity type of this seed. */
33 | type: 'artist' | 'track' | 'genre';
34 | }
35 |
36 | /**
37 | * The collection of recommendation seed objects with tracks provided from the spotify api..
38 | */
39 | export interface Recommendations {
40 | /** An array of recommendation seed objects. */
41 | seeds: RecommendationSeed[];
42 | /** An array of track object (simplified) ordered according to the parameters supplied. */
43 | tracks: SimplifiedTrack[];
44 | }
45 |
46 | /**
47 | * Just an extension for [RecommendationQuery].
48 | */
49 | export type RecommendationQueryExtension = Partial>;
50 |
51 | /**
52 | * The query paramater structure of the [/recommendations] endpoint.
53 | */
54 | export interface RecommendationQuery extends RecommendationQueryExtension {
55 | /** The target size of the list of recommended tracks. */
56 | limit?: number;
57 | /** An ISO 3166-1 alpha-2 country code or the string from_token. */
58 | market?: string;
59 | /** A comma separated list of Spotify IDs for seed artists. Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks and seed_genres **/
60 | seed_artists: string;
61 | /** A comma separated list of any genres in the set of available genre seeds. Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks and seed_genres. */
62 | seed_genres: string;
63 | /** A comma separated list of Spotify IDs for a seed track. Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks and seed_genres. */
64 | seed_tracks: string;
65 | }
--------------------------------------------------------------------------------
/typings/episode.d.ts:
--------------------------------------------------------------------------------
1 | import { SimplifiedShow } from "./show";
2 | import { ExternalUrl, Image, Restriction, Saved } from "./global";
3 |
4 | /**
5 | * The saved episode object.
6 | */
7 | export type SavedEpisode = Saved<'episode', Episode>;
8 |
9 | /**
10 | * The structure containing the complete details of the Spotify episode.
11 | */
12 | export interface Episode extends SimplifiedEpisode {
13 | /** The show on which the episode belongs. */
14 | show: SimplifiedShow;
15 | }
16 |
17 | /**
18 | * The structure containing the simplified details of the Spotify episode.
19 | */
20 | export interface SimplifiedEpisode {
21 | /** A URL to a 30 second preview (MP3 format) of the episode. null if not available. */
22 | audio_preview_url: string | null;
23 | /** A description of the episode. HTML tags are stripped away from this field, use html_description field in case HTML tags are needed. */
24 | description: string;
25 | /** The episode length in milliseconds. */
26 | duration_ms: number;
27 | /** Whether or not the episode has explicit content (true = yes it does; false = no it does not OR unknown). */
28 | explicit: boolean;
29 | /** External URLs for this episode */
30 | external_urls: ExternalUrl;
31 | /** A link to the Web API endpoint providing full details of the episode. */
32 | href: string;
33 | /** A description of the episode. This field may contain HTML tags. */
34 | html_description: string;
35 | /** The Spotify ID for the episode. */
36 | id: string;
37 | /** The cover art for the episode in various sizes, widest first. */
38 | images: Image[];
39 | /** True if the episode is hosted outside of Spotify’s CDN. */
40 | is_externally_hosted: boolean;
41 | /** True if the episode is playable in the given market. Otherwise false. */
42 | is_playable: boolean;
43 | /** The language used in the episode, identified by a ISO 639 code. */
44 | language?: string;
45 | /** A list of the languages used in the episode, identified by their ISO 639 code. */
46 | languages: string[];
47 | /** The name of the episode. */
48 | name: string;
49 | /** 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". */
50 | release_date: string;
51 | /** The precision with which release_date value is known: "year", "month", or "day". */
52 | release_date_precision: string;
53 | /** Included in the response when a content restriction is applied. */
54 | restrictions: Restriction[];
55 | /** 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’. */
56 | resume_point?: ResumePoint;
57 | /** The object type: “episode”. */
58 | type: 'episode';
59 | /** The Spotify URI for the episode */
60 | uri: string;
61 | }
62 |
63 | /**
64 | * An object containing the resume point.
65 | */
66 | export interface ResumePoint {
67 | /** Whether or not the episode has been fully played by the user. */
68 | fully_played: boolean;
69 | /** The user’s most recent position in the episode in milliseconds. */
70 | resume_position_ms: number;
71 | }
--------------------------------------------------------------------------------
/typings/global.d.ts:
--------------------------------------------------------------------------------
1 | import { Artist } from "./artist";
2 | import { Track } from "./track";
3 | import { SimplifiedAlbum } from "./album";
4 | import { SimplifiedEpisode } from "./episode";
5 | import { SimplifiedShow } from "./show";
6 | import { SimplifiedPlaylist } from "./playlist";
7 | import { SimplifiedAudiobook } from "./audiobook";
8 |
9 | /**
10 | * All the spotify element types
11 | */
12 | export type SpotifyType = 'user' | 'episode' | 'playlist' | 'show' | 'track' | 'album' | 'artist' | 'audiobook';
13 |
14 | /**
15 | * All the spotify search types.
16 | */
17 | export type SearchType = 'album' | 'artist' | 'track' | 'show' | 'episode' | 'playlist' | 'audiobook';
18 |
19 | /**
20 | * The spotify object containing the details of an image.
21 | */
22 | export interface Image {
23 | /** The image height in pixels. If unknown: null or not returned. */
24 | height: number | null;
25 | /** The source URL of the image. */
26 | url: string;
27 | /** The image width in pixels. If unknown: null or not returned. */
28 | width: number | null;
29 | }
30 |
31 | /**
32 | * The external urls object which contains the spotify url within it.
33 | */
34 | export interface ExternalUrl {
35 | /** The Spotify URL for the object. */
36 | spotify: string;
37 | }
38 |
39 | /**
40 | * The external ids object which contains the spotify id within it.
41 | */
42 | export interface ExternalID {
43 | /** International Article Number */
44 | ean: string;
45 | /** International Standard Recording Code */
46 | isrc: string;
47 | /** Universal Product Code */
48 | upc: string;
49 | }
50 |
51 | /**
52 | * The paging object is a form of collection of items from the spotify api.
53 | */
54 | export interface Paging {
55 | /** A link to the Web API endpoint returning the full result of the request. */
56 | href: string;
57 | /** The requested data. */
58 | items: T[];
59 | /** The maximum number of items in the response (as set in the query or by default). */
60 | limit: number;
61 | /** URL to the next page of items. (null if none) */
62 | next?: string;
63 | /** The offset of the items returned (as set in the query or by default) */
64 | offset: number;
65 | /** URL to the previous page of items. (null if none) */
66 | previous?: string;
67 | /** The total number of items available to return. */
68 | total: number;
69 | }
70 |
71 | /**
72 | * The cursor object having before and after keys of the items.
73 | */
74 | export interface Cursor {
75 | /** The cursor to use as key to find the next page of items. */
76 | after: string;
77 | /** The cursor to use as key to find the previous page of items. */
78 | before: string;
79 | }
80 |
81 |
82 | /**
83 | * The paging object but with a additional cursor field.
84 | */
85 | export interface CursorPaging extends Omit, 'offset' | 'previous'> {
86 | /** The cursors used to find the next set of items. */
87 | cursors: Cursor;
88 | }
89 |
90 | /**
91 | * The copyright object contains the type and the name of copyright.
92 | */
93 | export interface Copyright {
94 | /** The text of copyright. */
95 | text: string;
96 | /** The type of copyright. */
97 | type: 'C' | 'P';
98 | }
99 |
100 | /**
101 | * The object containing the reason of restriction by the spotify api.
102 | */
103 | export interface Restriction {
104 | /** The reason for the restriction. */
105 | reason: 'market' | 'product' | 'explicit';
106 | }
107 |
108 | /**
109 | * The error response sent by the spotify api during unusual status codes.
110 | */
111 | export interface ErrorResponse {
112 | /** A short description of the cause of the error. */
113 | message: string;
114 | /** The HTTP status code (also returned in the response header; see Response Status Codes for more information). */
115 | status: number;
116 | }
117 |
118 | /**
119 | * The object containing the saved elements and the timestamp when they were added.
120 | */
121 | export type Saved = { added_at: string } & Record;
122 |
123 | /**
124 | * The object structure returned by the [/search] endpoint.
125 | */
126 | export interface SearchContent {
127 | /** The episode search results. */
128 | episodes?: Paging;
129 | /** The show search results. */
130 | shows?: Paging;
131 | /** The track search results. */
132 | tracks?: Paging