Skip to content

Commit 20ceacb

Browse files
cloughneyJMPerez
cloughney
authored and
JMPerez
committed
Add typings for player endpoints (#90)
* add typings for player endpoints
1 parent e0a2695 commit 20ceacb

File tree

2 files changed

+238
-11
lines changed

2 files changed

+238
-11
lines changed

‎src/typings/spotify-api.d.ts

Lines changed: 56 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,23 @@ declare namespace SpotifyApi {
103103
target_valence?: number
104104
}
105105

106+
interface RecentlyPlayedParameterObject {
107+
limit?: number;
108+
after?: number;
109+
before?: number;
110+
}
111+
112+
interface TransferPlaybackParameterObject {
113+
play?: boolean;
114+
}
115+
116+
interface TrackRelinkingParameterObject {
117+
market?: string;
118+
}
119+
120+
interface DeviceSpecificParameterObject {
121+
device_id?: string;
122+
}
106123

107124
//
108125
// Responses from the Spotify Web API in the same order as in the API endpoint docs seen here:
@@ -123,7 +140,6 @@ declare namespace SpotifyApi {
123140
snapshot_id: string
124141
}
125142

126-
127143
// Spotify API Endpoints:
128144

129145
/**
@@ -603,7 +619,13 @@ declare namespace SpotifyApi {
603619
*/
604620
interface UsersFollowPlaylistReponse extends Array<boolean> {}
605621

622+
interface UserDevicesResponse {
623+
devices: UserDevice[];
624+
}
625+
626+
interface CurrentPlaybackResponse extends CurrentlyPlayingObject, PlaybackObject {}
606627

628+
interface CurrentlyPlayingResponse extends CurrentlyPlayingObject {}
607629

608630
//
609631
// Objects from the Object Models of the Spotify Web Api, ordered alphabetically.
@@ -961,19 +983,45 @@ declare namespace SpotifyApi {
961983
* [](https://developer.spotify.com/web-api/object-model/#context-object)
962984
*/
963985
interface ContextObject {
964-
type: string,
965-
href: string,
966-
external_urls: ExternalUrlObject,
967-
uri: string
986+
type: ContextObjectType;
987+
href: string | null;
988+
external_urls: ExternalUrlObject | null;
989+
uri: string;
968990
}
969991

970992
/**
971993
* Play History Object
972994
* [](https://developer.spotify.com/web-api/web-api-personalization-endpoints/get-recently-played/#play-history-object)
973995
*/
974996
interface PlayHistoryObject {
975-
track: TrackObjectSimplified,
976-
played_at: string,
977-
context: ContextObject
997+
track: TrackObjectSimplified;
998+
played_at: string;
999+
context: ContextObject;
1000+
}
1001+
1002+
interface PlaybackObject {
1003+
shuffle_state: boolean;
1004+
repeat_state: PlaybackRepeatState;
9781005
}
1006+
1007+
interface CurrentlyPlayingObject {
1008+
timestamp: number;
1009+
device: UserDevice;
1010+
progress_ms: number | null;
1011+
is_playing: boolean;
1012+
item: TrackObjectFull | null;
1013+
context: ContextObject | null;
1014+
}
1015+
1016+
interface UserDevice {
1017+
id: string | null;
1018+
is_active: boolean;
1019+
is_restricted: boolean;
1020+
name: string;
1021+
type: string;
1022+
volume_percent: number | null;
1023+
}
1024+
1025+
type ContextObjectType = 'artist' | 'playlist' | 'album';
1026+
type PlaybackRepeatState = 'off' | 'track' | 'context';
9791027
}

‎src/typings/spotify-web-api.d.ts

Lines changed: 182 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,16 @@ export = SpotifyWebApi;
1414
declare var SpotifyWebApi: SpotifyWebApiJs.SpotifyWebApiJsStatic;
1515

1616
declare namespace SpotifyWebApiJs {
17+
interface VoidResultsCallback {
18+
(error: ErrorObject): any;
19+
}
20+
1721
/**
1822
* An optional callback that receives 2 parameters. The first
1923
* one is the error object (null if no error), and the second is the value if the request succeeded.
2024
*/
2125
interface ResultsCallback<T> {
22-
(error: ErrorObject, value: T) : any
26+
(error: ErrorObject, value: T): any;
2327
}
2428

2529
/**
@@ -207,7 +211,9 @@ declare namespace SpotifyWebApiJs {
207211
* one is the error object (null if no error), and the second is the value if the request succeeded.
208212
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
209213
*/
210-
getMyRecentlyPlayedTracks(options?: Object, callback?: ResultsCallback<SpotifyApi.UsersRecentlyPlayedTracksResponse>) : Promise<SpotifyApi.UsersRecentlyPlayedTracksResponse>;
214+
getMyRecentlyPlayedTracks(options?: SpotifyApi.RecentlyPlayedParameterObject) : Promise<SpotifyApi.UsersRecentlyPlayedTracksResponse>;
215+
getMyRecentlyPlayedTracks(options: SpotifyApi.RecentlyPlayedParameterObject, callback: ResultsCallback<SpotifyApi.UsersRecentlyPlayedTracksResponse>): void;
216+
getMyRecentlyPlayedTracks(callback: ResultsCallback<SpotifyApi.UsersRecentlyPlayedTracksResponse>): void;
211217

212218
/**
213219
* Adds the current user as a follower of one or more other Spotify users.
@@ -877,7 +883,180 @@ declare namespace SpotifyWebApiJs {
877883
* one is the error object (null if no error), and the second is the value if the request succeeded.
878884
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
879885
*/
880-
getAvailableGenreSeeds(callback?: ResultsCallback<SpotifyApi.AvailableGenreSeedsResponse>) : Promise<SpotifyApi.AvailableGenreSeedsResponse>
886+
getAvailableGenreSeeds(callback?: ResultsCallback<SpotifyApi.AvailableGenreSeedsResponse>) : Promise<SpotifyApi.AvailableGenreSeedsResponse>;
887+
888+
/**
889+
* Get information about a user’s available devices.
890+
* See [Get a User’s Available Devices](https://developer.spotify.com/web-api/get-a-users-available-devices/) on
891+
* the Spotify Developer site for more information about the endpoint.
892+
*
893+
* @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first
894+
* one is the error object (null if no error), and the second is the value if the request succeeded.
895+
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
896+
*/
897+
getMyDevices(): Promise<SpotifyApi.UserDevicesResponse>;
898+
getMyDevices(callback: ResultsCallback<SpotifyApi.UserDevicesResponse>): void;
899+
900+
/**
901+
* Get information about the user’s current playback state, including track, track progress, and active device.
902+
* See [Get Information About The User’s Current Playback](https://developer.spotify.com/web-api/get-information-about-the-users-current-playback/) on
903+
* the Spotify Developer site for more information about the endpoint.
904+
*
905+
* @param {Object} options A JSON object with options that can be passed.
906+
* @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first
907+
* one is the error object (null if no error), and the second is the value if the request succeeded.
908+
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
909+
*/
910+
getMyCurrentPlaybackState(options?: SpotifyApi.TrackRelinkingParameterObject): Promise<SpotifyApi.CurrentPlaybackResponse>;
911+
getMyCurrentPlaybackState(options: SpotifyApi.TrackRelinkingParameterObject, callback: ResultsCallback<SpotifyApi.CurrentPlaybackResponse>): void;
912+
getMyCurrentPlaybackState(callback: ResultsCallback<SpotifyApi.CurrentPlaybackResponse>): void;
913+
914+
/**
915+
* Get the object currently being played on the user’s Spotify account.
916+
* See [Get the User’s Currently Playing Track](https://developer.spotify.com/web-api/get-the-users-currently-playing-track/) on
917+
* the Spotify Developer site for more information about the endpoint.
918+
*
919+
* @param {Object} options A JSON object with options that can be passed.
920+
* @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first
921+
* one is the error object (null if no error), and the second is the value if the request succeeded.
922+
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
923+
*/
924+
getMyCurrentPlayingTrack(options?: SpotifyApi.TrackRelinkingParameterObject): Promise<SpotifyApi.CurrentlyPlayingResponse>;
925+
getMyCurrentPlayingTrack(options: SpotifyApi.TrackRelinkingParameterObject, callback: ResultsCallback<SpotifyApi.CurrentlyPlayingResponse>): void;
926+
getMyCurrentPlayingTrack(callback: ResultsCallback<SpotifyApi.CurrentlyPlayingResponse>): void;
927+
928+
/**
929+
* Transfer playback to a new device and determine if it should start playing.
930+
* See [Transfer a User’s Playback](https://developer.spotify.com/web-api/transfer-a-users-playback/) on
931+
* the Spotify Developer site for more information about the endpoint.
932+
*
933+
* @param {Array<string>} deviceIds A JSON array containing the ID of the device on which playback should be started/transferred.
934+
* @param {Object} options A JSON object with options that can be passed.
935+
* @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first
936+
* one is the error object (null if no error), and the second is the value if the request succeeded.
937+
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
938+
*/
939+
transferMyPlayback(deviceIds: string[], options?: SpotifyApi.TransferPlaybackParameterObject): Promise<void>;
940+
transferMyPlayback(deviceIds: string[], options: SpotifyApi.TransferPlaybackParameterObject, callback: VoidResultsCallback): void;
941+
transferMyPlayback(deviceIds: string[], callback: VoidResultsCallback): void;
942+
943+
/**
944+
* Start a new context or resume current playback on the user’s active device.
945+
* See [Start/Resume a User’s Playback](https://developer.spotify.com/web-api/start-a-users-playback/) on
946+
* the Spotify Developer site for more information about the endpoint.
947+
*
948+
* @param {Object} options A JSON object with options that can be passed.
949+
* @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first
950+
* one is the error object (null if no error), and the second is the value if the request succeeded.
951+
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
952+
*/
953+
play(options?: SpotifyApi.DeviceSpecificParameterObject): Promise<void>;
954+
play(options: SpotifyApi.DeviceSpecificParameterObject, callback: VoidResultsCallback): void;
955+
play(callback: VoidResultsCallback): void;
956+
957+
/**
958+
* Pause playback on the user’s account.
959+
* See [Pause a User’s Playback](https://developer.spotify.com/web-api/pause-a-users-playback/) on
960+
* the Spotify Developer site for more information about the endpoint.
961+
*
962+
* @param {Object} options A JSON object with options that can be passed.
963+
* @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first
964+
* one is the error object (null if no error), and the second is the value if the request succeeded.
965+
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
966+
*/
967+
pause(options?: SpotifyApi.DeviceSpecificParameterObject): Promise<void>;
968+
pause(options: SpotifyApi.DeviceSpecificParameterObject, callback: VoidResultsCallback): void;
969+
pause(callback: VoidResultsCallback): void;
970+
971+
/**
972+
* Skips to next track in the user’s queue.
973+
* See [Skip User’s Playback To Next Track](https://developer.spotify.com/web-api/skip-users-playback-to-next-track/) on
974+
* the Spotify Developer site for more information about the endpoint.
975+
*
976+
* @param {Object} options A JSON object with options that can be passed.
977+
* @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first
978+
* one is the error object (null if no error), and the second is the value if the request succeeded.
979+
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
980+
*/
981+
skipToNext(options?: SpotifyApi.DeviceSpecificParameterObject): Promise<void>;
982+
skipToNext(options: SpotifyApi.DeviceSpecificParameterObject, callback: VoidResultsCallback): void;
983+
skipToNext(callback: VoidResultsCallback): void;
984+
985+
/**
986+
* Skips to previous track in the user’s queue.
987+
* Note that this will ALWAYS skip to the previous track, regardless of the current track’s progress.
988+
* Returning to the start of the current track should be performed using `.seek()`
989+
* See [Skip User’s Playback To Previous Track](https://developer.spotify.com/web-api/skip-users-playback-to-next-track/) on
990+
* the Spotify Developer site for more information about the endpoint.
991+
*
992+
* @param {Object} options A JSON object with options that can be passed.
993+
* @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first
994+
* one is the error object (null if no error), and the second is the value if the request succeeded.
995+
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
996+
*/
997+
skipToPrevious(options?: SpotifyApi.DeviceSpecificParameterObject): Promise<void>;
998+
skipToPrevious(options: SpotifyApi.DeviceSpecificParameterObject, callback: VoidResultsCallback): void;
999+
skipToPrevious(callback: VoidResultsCallback): void;
1000+
1001+
/**
1002+
* Seeks to the given position in the user’s currently playing track.
1003+
* See [Seek To Position In Currently Playing Track](https://developer.spotify.com/web-api/seek-to-position-in-currently-playing-track/) on
1004+
* the Spotify Developer site for more information about the endpoint.
1005+
*
1006+
* @param {number} position_ms The position in milliseconds to seek to. Must be a positive number.
1007+
* @param {Object} options A JSON object with options that can be passed.
1008+
* @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first
1009+
* one is the error object (null if no error), and the second is the value if the request succeeded.
1010+
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
1011+
*/
1012+
seek(position: number, options?: SpotifyApi.DeviceSpecificParameterObject): Promise<void>;
1013+
seek(position: number, options: SpotifyApi.DeviceSpecificParameterObject, callback: VoidResultsCallback): void;
1014+
seek(position: number, callback: VoidResultsCallback): void;
1015+
1016+
/**
1017+
* Set the repeat mode for the user’s playback. Options are repeat-track, repeat-context, and off.
1018+
* See [Set Repeat Mode On User’s Playback](https://developer.spotify.com/web-api/set-repeat-mode-on-users-playback/) on
1019+
* the Spotify Developer site for more information about the endpoint.
1020+
*
1021+
* @param {String} state A string set to 'track', 'context' or 'off'.
1022+
* @param {Object} options A JSON object with options that can be passed.
1023+
* @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first
1024+
* one is the error object (null if no error), and the second is the value if the request succeeded.
1025+
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
1026+
*/
1027+
setRepeat(state: SpotifyApi.PlaybackRepeatState, options?: SpotifyApi.DeviceSpecificParameterObject): Promise<void>;
1028+
setRepeat(state: SpotifyApi.PlaybackRepeatState, options: SpotifyApi.DeviceSpecificParameterObject, callback: VoidResultsCallback): void;
1029+
setRepeat(state: SpotifyApi.PlaybackRepeatState, callback: VoidResultsCallback): void;
1030+
1031+
/**
1032+
* Set the volume for the user’s current playback device.
1033+
* See [Set Volume For User’s Playback](https://developer.spotify.com/web-api/set-volume-for-users-playback/) on
1034+
* the Spotify Developer site for more information about the endpoint.
1035+
*
1036+
* @param {number} volume_percent The volume to set. Must be a value from 0 to 100 inclusive.
1037+
* @param {Object} options A JSON object with options that can be passed.
1038+
* @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first
1039+
* one is the error object (null if no error), and the second is the value if the request succeeded.
1040+
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
1041+
*/
1042+
setVolume(volumePercent: number, options?: SpotifyApi.DeviceSpecificParameterObject): Promise<void>;
1043+
setVolume(volumePercent: number, options: SpotifyApi.DeviceSpecificParameterObject, callback: VoidResultsCallback): void;
1044+
setVolume(volumePercent: number, callback: VoidResultsCallback): void;
1045+
1046+
/**
1047+
* Toggle shuffle on or off for user’s playback.
1048+
* See [Toggle Shuffle For User’s Playback](https://developer.spotify.com/web-api/toggle-shuffle-for-users-playback/) on
1049+
* the Spotify Developer site for more information about the endpoint.
1050+
*
1051+
* @param {bool} state Whether or not to shuffle user's playback.
1052+
* @param {Object} options A JSON object with options that can be passed.
1053+
* @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first
1054+
* one is the error object (null if no error), and the second is the value if the request succeeded.
1055+
* @return {Object} Null if a callback is provided, a `Promise` object otherwise
1056+
*/
1057+
setShuffle(state: boolean, options?: SpotifyApi.DeviceSpecificParameterObject): Promise<void>;
1058+
setShuffle(state: boolean, options: SpotifyApi.DeviceSpecificParameterObject, callback: VoidResultsCallback): void;
1059+
setShuffle(state: boolean, callback: VoidResultsCallback): void;
8811060

8821061
/**
8831062
* Gets the access token in use.

0 commit comments

Comments
 (0)