From 2d6b8ff0cf2f110db871368296448b7894e98703 Mon Sep 17 00:00:00 2001 From: Niels Kristian Hansen Skovmand Date: Fri, 25 Dec 2015 11:37:55 +0100 Subject: [PATCH] Typings for the Spotify Web Api --- spotify-api/spotify-api.d.ts | 679 +++++++++++++++++++++++++++++++++++ 1 file changed, 679 insertions(+) create mode 100644 spotify-api/spotify-api.d.ts diff --git a/spotify-api/spotify-api.d.ts b/spotify-api/spotify-api.d.ts new file mode 100644 index 0000000000..7b6e6c8a79 --- /dev/null +++ b/spotify-api/spotify-api.d.ts @@ -0,0 +1,679 @@ +// Type definitions for The Spotify Web API v1.0 +// Project: https://developer.spotify.com/web-api/ +// Definitions by: Niels Kristian Hansen Skovmand, https://github.com/skovmand +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped + +declare module SpotifyApi { + + // + // Parameter Objects for searching + // + + /** + * Object for search parameters for searching for tracks, playlists, artists or albums. + * See: [Search for an item](https://developer.spotify.com/web-api/search-item/) + * + * q and type are not optional in the API, however they are marked as optional here, since various libraries + * implement them as function call parameters instead. This could be changed. + * + * @param q Required. The search query's keywords (and optional field filters and operators). + * @param type Required. A comma-separated list of item types to search across. Valid types are: album, artist, playlist, and track. + * @param market Optional. An ISO 3166-1 alpha-2 country code or the string from_token + * @param limit Optional. The maximum number of results to return. Default: 20. Minimum: 1. Maximum: 50. + * @param offset Optional. The index of the first result to return. Default: 0 (i.e., the first result). Maximum offset: 100.000. Use with limit to get the next page of search results. + */ + interface SearchForItemParameterObject { + q?: string; + type?: string; + market?: string; + limit?: number; + offset?: number; + } + + + // + // Responses from the Spotify Web API in the same order as in the API endpoint docs seen here: + // [API Endpoint Reference](https://developer.spotify.com/web-api/endpoint-reference/) + // + + // Generic interfaces for re-use: + + /** + * Void Response + */ + interface VoidResponse {} + + /** + * Response with Playlist Snapshot + */ + interface PlaylistSnapshotResponse { + snapshot_id: string + } + + + // Spotify API Endpoints: + + /** + * Get an Album + * GET /v1/albums/{id} + */ + interface SingleAlbumResponse extends AlbumObjectFull {} + + /** + * Get Several Albums + * GET /v1/albums + */ + interface MultipleAlbumsResponse { + albums: AlbumObjectFull[] + } + + /** + * Get an Album’s Tracks + * GET /v1/albums/{id}/tracks + */ + interface AlbumTracksResponse extends PagingObject {} + + /** + * Get an Artist + * GET /v1/artists/{id} + */ + interface SingleArtistResponse extends ArtistObjectFull {} + + /** + * Get Several Artists + * GET /v1/artists + */ + interface MultipleArtistsResponse { + artists: ArtistObjectFull[] + } + + /** + * Get an Artist’s Albums + * GET /v1/artists/{id}/albums + */ + interface ArtistsAlbumsResponse extends PagingObject {} + + /** + * Get an Artist’s Top Tracks + * GET /v1/artists/{id}/top-tracks + */ + interface ArtistsTopTracksResponse { + tracks: TrackObjectFull[] + } + + /** + * Get an Artist’s Related Artists + * GET /v1/artists/{id}/related-artists + */ + interface ArtistsRelatedArtistsResponse { + artists: PagingObject + } + + /** + * Get a list of featured playlists + * GET /v1/browse/featured-playlists + */ + interface ListOfFeaturedPlaylistsResponse { + message: string, + playlists: PagingObject + } + + /** + * Get a list of new releases + * GET /v1/browse/new-releases + */ + interface ListOfNewReleasesResponse { + message: string, + albums: PagingObject + } + + /** + * Get a list of categories + * GET /v1/browse/categories + */ + interface MultipleCategoriesResponse { + categories: PagingObject + } + + /** + * Get a category + * GET /v1/browse/categories/{category_id} + */ + interface SingleCategoryResponse extends CategoryObject {} + + /** + * Get a categorys playlists + * GET /v1/browse/categories/{id}/playlists + */ + interface CategoryPlaylistsReponse { + playlists: PagingObject + } + + /** + * Get Current User’s Profile + * GET /v1/me + */ + interface CurrentUsersProfileResponse extends UserObjectPrivate {} + + /** + * Get User’s Followed Artists + * GET /v1/me/following?type=artist + */ + interface UsersFollowedArtistsResponse { + artists: PagingObject + } + + /** + * Follow artists or users + * PUT /v1/me/following + */ + interface FollowArtistsOrUsersResponse extends VoidResponse {} + + /** + * Unfollow artists or users + * DELETE /v1/me/following + */ + interface UnfollowArtistsOrUsersResponse extends VoidResponse {} + + /** + * Check if User Follows Users or Artists + * GET /v1/me/following/contains + */ + interface UserFollowsUsersOrArtistsResponse extends Array {} + + /** + * Follow a Playlist + * PUT /v1/users/{owner_id}/playlists/{playlist_id}/followers + */ + interface FollowAPlaylistReponse extends VoidResponse {} + + /** + * Unfollow a Playlist + * DELETE /v1/users/{owner_id}/playlists/{playlist_id}/followers + */ + interface UnfollowPlaylistReponse extends VoidResponse {} + + /** + * Save tracks for user + * PUT /v1/me/tracks?ids={ids} + */ + interface SaveTracksForUserResponse extends VoidResponse {} + + /** + * Get user's saved tracks + * GET /v1/me/tracks + */ + interface UsersSavedTracksResponse extends PagingObject {} + + /** + * Remove User’s Saved Tracks + * DELETE /v1/me/tracks?ids={ids} + */ + interface RemoveUsersSavedTracksResponse extends VoidResponse {} + + /** + * Check User’s Saved Tracks + * GET /v1/me/tracks/contains + */ + interface CheckUsersSavedTracksResponse extends Array {} + + /** + * Save albums for user + * PUT /v1/me/albums?ids={ids} + */ + interface SaveAlbumsForUserResponse extends VoidResponse {} + + /** + * Get user's saved albums + * GET /v1/me/albums + */ + interface UsersSavedAlbumsResponse extends PagingObject {} + + /** + * Remove Albums for Current User + * DELETE /v1/me/albums?ids={ids} + */ + interface RemoveAlbumsForCurrentUserResponse extends VoidResponse {} + + /** + * Check user's saved albums + * DELETE /v1/me/albums/contains?ids={ids} + */ + interface CheckUserSavedAlbumsResponse extends Array {} + + /** + * Search for an album + * GET /v1/search?type=album + */ + interface AlbumSearchResponse { + albums: PagingObject + } + + /** + * Search for an artist + * GET /v1/search?type=artist + */ + interface ArtistSearchResponse { + artists: PagingObject + } + + /** + * Search for a playlist + * GET /v1/search?type=playlist + */ + interface PlaylistSearchResponse { + playlists: PagingObject + } + + /** + * Search for a track + * GET /v1/search?type=track + */ + interface TrackSearchResponse { + tracks: PagingObject + } + + /** + * Get a track + * GET /v1/tracks/{id} + */ + interface SingleTrackResponse extends TrackObjectFull {} + + /** + * Get multiple tracks + * GET /v1/tracks?ids={ids} + */ + interface MultipleTracksResponse { + tracks: TrackObjectFull[] + } + + /** + * Get user profile + * GET /v1/users/{user_id} + */ + interface UserProfileResponse extends UserObjectPublic {} + + /** + * Get a list of a user's playlists + * GET /v1/users/{user_id}/playlists + */ + interface ListOfUsersPlaylistsResponse extends PagingObject {} + + /** + * Get a list of the current user's playlists + * GET /v1/me/playlists + */ + interface ListOfCurrentUsersPlaylistsResponse extends PagingObject {} + + /** + * Get a playlist + * GET /v1/users/{user_id}/playlists/{playlist_id} + */ + interface SinglePlaylistResponse extends PlaylistObjectFull {} + + /** + * Get a playlist's tracks + * GET /v1/users/{user_id}/playlists/{playlist_id}/tracks + */ + interface PlaylistTrackResponse extends PagingObject {} + + /** + * Create a Playlist + * POST /v1/users/{user_id}/playlists + */ + interface CreateAPlaylistResponse extends PlaylistObjectFull {} + + /** + * Change a Playlist’s Details + * PUT /v1/users/{user_id}/playlists/{playlist_id} + */ + interface ChangePlaylistDetailsReponse extends VoidResponse {} + + /** + * Add Tracks to a Playlist + * POST /v1/users/{user_id}/playlists/{playlist_id}/tracks + */ + interface AddTracksToPlaylistResponse extends PlaylistSnapshotResponse {} + + /** + * Remove Tracks from a Playlist + * DELETE /v1/users/{user_id}/playlists/{playlist_id}/tracks + */ + interface RemoveTracksFromPlaylistResponse extends PlaylistSnapshotResponse {} + + /** + * Reorder a Playlist’s Tracks + * PUT /v1/users/{user_id}/playlists/{playlist_id}/tracks + */ + interface ReorderPlaylistTracksResponse extends PlaylistSnapshotResponse {} + + /** + * Replace a Playlist’s Tracks + * PUT /v1/users/{user_id}/playlists/{playlist_id}/tracks + */ + interface ReplacePlaylistTracksResponse extends VoidResponse {} + + /** + * Check if Users Follow a Playlist + * GET /v1/users/{user_id}/playlists/{playlist_id}/followers/contains + */ + interface UsersFollowPlaylistReponse extends Array {} + + + + // + // Objects from the Object Models of the Spotify Web Api + // [Object Model](https://developer.spotify.com/web-api/object-model) + // + + // + // The Paging Object wrappers used for retrieving collections from the Spotify API. + // + + /** + * BasePagingObject which the IPagingObject and ICursorBasedPagingObject extend from. + * Doesn't exist in itself in the spotify API. + */ + interface BasePagingObject { + href: string, + items: T[], + limit: number, + next: string, + offset: number, + total: number + } + + /** + * Paging Object wrapper used for retrieving collections from the Spotify API. + * [](https://developer.spotify.com/web-api/object-model/#paging-object) + */ + interface PagingObject extends BasePagingObject { + previous: string, + } + + /** + * Cursor Based Paging Object wrappers used for retrieving collections from the Spotify API. + * [](https://developer.spotify.com/web-api/object-model/#cursor-based-paging-object) + */ + interface CursorBasedPagingObject extends BasePagingObject { + cursors: CursorObject + } + + + + // + // All other objects of the Object Models from the Spotify Web Api, ordered alphabetically. + // + + /** + * Full Album Object + * [album object (full)](https://developer.spotify.com/web-api/object-model/#album-object-simplified) + */ + interface AlbumObjectFull extends AlbumObjectSimplified { + artists: ArtistObjectSimplified[], + copyrights: CopyrightObject[], + external_ids: ExternalIdObject, + genres: string[], + popularity: number, + release_date: string, + release_date_precision: string, + tracks: PagingObject, + } + + /** + * Simplified Album Object + * [album object (simplified)](https://developer.spotify.com/web-api/object-model/#album-object-simplified) + */ + interface AlbumObjectSimplified { + album_type: string, + available_markets: string[], + external_urls: ExternalUrlObject, + href: string, + id: string, + images: ImageObject[], + name: string, + type: string, + uri: string + } + + /** + * Full Artist Object + * [artist object (full)](https://developer.spotify.com/web-api/object-model/) + */ + interface ArtistObjectFull extends ArtistObjectSimplified { + followers: FollowersObject, + genres: string[], + images: ImageObject[], + popularity: number, + } + + /** + * Simplified Artist Object + * [artist object (simplified)](https://developer.spotify.com/web-api/object-model/) + */ + interface ArtistObjectSimplified { + external_urls: ExternalUrlObject, + href: string, + id: string, + name: string, + type: string, + uri: string + } + + /** + * Category Object + * [category object](https://developer.spotify.com/web-api/object-model/) + */ + interface CategoryObject { + href: string, + icons: ImageObject[], + id: string, + name: string + } + + /** + * Copyright object + * [copyright object](https://developer.spotify.com/web-api/object-model/) + */ + interface CopyrightObject { + text: string, + type: string + } + + /** + * Cursor object + * [cursor object](https://developer.spotify.com/web-api/object-model/) + */ + interface CursorObject { + after: string + } + + /** + * Error object + * [error object](https://developer.spotify.com/web-api/object-model/) + */ + interface ErrorObject { + status: number, + message: string + } + + /** + * External Id object + * [](https://developer.spotify.com/web-api/object-model/) + * + * Note that there might be other types available, it couldn't be found in the docs. + */ + interface ExternalIdObject { + isrc?: string, + ean?: string, + upc?: string + } + + /** + * External Url Object + * [](https://developer.spotify.com/web-api/object-model/) + * + * Note that there might be other types available, it couldn't be found in the docs. + */ + interface ExternalUrlObject { + spotify: string + } + + /** + * Followers Object + * [](https://developer.spotify.com/web-api/object-model/) + */ + interface FollowersObject { + href: string, + total: number + } + + /** + * Image Object + * [](https://developer.spotify.com/web-api/object-model/) + */ + interface ImageObject { + height?: number, + url: string, + width?: number + } + + /** + * Base Playlist Object. Does not in itself exist in Spotify Web Api, + * but needs to be made since the tracks types vary in the Full and Simplified versions. + */ + interface PlaylistBaseObject { + collaborative: boolean, + external_urls: ExternalUrlObject, + href: string, + id: string, + images: ImageObject[], + name: string, + owner: UserObjectPublic, + public: boolean, + snapshot_id: string, + type: string, + uri: string + } + + /** + * Playlist Object Full + * [](https://developer.spotify.com/web-api/object-model/) + */ + interface PlaylistObjectFull extends PlaylistBaseObject { + description: string, + followers: FollowersObject, + tracks: PagingObject + } + + /** + * Playlist Object Simplified + * [](https://developer.spotify.com/web-api/object-model/) + */ + interface PlaylistObjectSimplified extends PlaylistBaseObject { + tracks: { + href: string, + total: number + } + } + + /** + * The Track Object in Playlists + * [](https://developer.spotify.com/web-api/object-model/) + */ + interface PlaylistTrackObject { + added_at: string, + added_by: UserObjectPublic, + is_local: boolean, + track: TrackObjectFull + } + + /** + * Saved Track Object in Playlists + * [](https://developer.spotify.com/web-api/object-model/) + */ + interface SavedTrackObject { + added_at: string, + track: TrackObjectFull + } + + /** + * Saved Track Object in Playlists + * [](https://developer.spotify.com/web-api/object-model/) + */ + interface SavedAlbumObject { + added_at: string, + album: AlbumObjectFull + } + + /** + * Full Track Object + * [track object (full)](https://developer.spotify.com/web-api/object-model/#track-object-full) + */ + interface TrackObjectFull extends TrackObjectSimplified { + album: AlbumObjectSimplified, + external_ids: ExternalIdObject, + popularity: number + } + + /** + * Simplified Track Object + * [track object (simplified)](https://developer.spotify.com/web-api/object-model/#track-object-simplified) + */ + interface TrackObjectSimplified { + artists: ArtistObjectSimplified[], + available_markets: string[], + disc_number: number, + duration_ms: number, + explicit: boolean, + external_urls: ExternalUrlObject, + href: string, + id: string, + is_playable?: boolean, + linked_from?: TrackLinkObject, + name: string, + preview_url: string, + track_number: number, + type: string, + uri: string + } + + /** + * Track Link Object + * [](https://developer.spotify.com/web-api/object-model/#track-object-simplified) + */ + interface TrackLinkObject { + external_urls: ExternalUrlObject, + href: string, + id: string, + type: string, + uri: string + } + + /** + * User Object (Private) + * [](https://developer.spotify.com/web-api/object-model/#track-object-simplified) + */ + interface UserObjectPrivate extends UserObjectPublic { + birthdate: string, + country: string, + email: string, + product: string + } + + /** + * User Object (Public) + * [](https://developer.spotify.com/web-api/object-model/#track-object-simplified) + */ + interface UserObjectPublic { + display_name?: string, + external_urls: ExternalUrlObject, + followers?: FollowersObject, + href: string, + id: string, + images?: ImageObject[], + type: string, + uri: string + } + +} \ No newline at end of file