From c75bf4dda200f3f486197c64c6ad1b74bd46d644 Mon Sep 17 00:00:00 2001 From: Artem Melnyk Date: Mon, 26 Feb 2024 11:13:24 +0100 Subject: [PATCH] chore: add jsdoc annotations for premium only endpoints --- .vscode/settings.json | 5 +++ README.md | 40 +++++++++++---------- endpoints/audiobook/audiobook.types.ts | 2 +- endpoints/episode/episode.endpoints.ts | 5 ++- endpoints/episode/episode.types.ts | 2 +- endpoints/genre/genre.endpoints.ts | 4 ++- endpoints/market/market.endpoints.ts | 4 ++- endpoints/player/player.endpoints.ts | 48 +++++++++++++++++--------- tsconfig.json | 2 +- 9 files changed, 71 insertions(+), 41 deletions(-) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..047daf3 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "[typescript]": { + "editor.defaultFormatter": "denoland.vscode-deno" + } +} diff --git a/README.md b/README.md index c7fb883..620bc24 100644 --- a/README.md +++ b/README.md @@ -214,12 +214,13 @@ import { PageIterator } from "@soundify/web-api/pagination"; const client = new SpotifyClient("YOUR_ACCESS_TOKEN"); const playlistIter = new PageIterator( - (offset) => getPlaylistTracks(client, "37i9dQZEVXbMDoHDwVN2tF", { - // you can find the max limit for specific endpoint - // in spotify docs or in the jsdoc comments of this property - limit: 50, - offset, - }), + (offset) => + getPlaylistTracks(client, "37i9dQZEVXbMDoHDwVN2tF", { + // you can find the max limit for specific endpoint + // in spotify docs or in the jsdoc comments of this property + limit: 50, + offset, + }), ); // iterate over all tracks in the playlist @@ -233,12 +234,13 @@ console.log(allTracks.length); // Want to get the last 100 items? No problem const lastHundredTracks = new PageIterator( - (offset) => getPlaylistTracks( - client, - "37i9dQZEVXbMDoHDwVN2tF", - { limit: 50, offset } - ), - { initialOffset: -100 }, // this will work just as `Array.slice(-100)` + (offset) => + getPlaylistTracks( + client, + "37i9dQZEVXbMDoHDwVN2tF", + { limit: 50, offset }, + ), + { initialOffset: -100 }, // this will work just as `Array.slice(-100)` ).collect(); ``` @@ -249,21 +251,23 @@ import { CursorPageIterator } from "@soundify/web-api/pagination"; const client = new SpotifyClient("YOUR_ACCESS_TOKEN"); // loop over all followed artists -for await (const artist of new CursorPageIterator( - opts => getFollowedArtists(client, { limit: 50, after: opts.after }) -)) { +for await ( + const artist of new CursorPageIterator( + (opts) => getFollowedArtists(client, { limit: 50, after: opts.after }), + ) +) { console.log(artist.name); } // or collect all followed artists into an array const artists = await new CursorPageIterator( - opts => getFollowedArtists(client, { limit: 50, after: opts.after }) + (opts) => getFollowedArtists(client, { limit: 50, after: opts.after }), ).collect(); // get all followed artists starting from Radiohead const artists = await new CursorPageIterator( - opts => getFollowedArtists(client, { limit: 50, after: opts.after }), - { initialAfter: "4Z8W4fKeB5YxbusRsdQVPb" } // let's start from Radiohead + (opts) => getFollowedArtists(client, { limit: 50, after: opts.after }), + { initialAfter: "4Z8W4fKeB5YxbusRsdQVPb" }, // let's start from Radiohead ).collect(); ``` diff --git a/endpoints/audiobook/audiobook.types.ts b/endpoints/audiobook/audiobook.types.ts index 8cf465c..e158a15 100644 --- a/endpoints/audiobook/audiobook.types.ts +++ b/endpoints/audiobook/audiobook.types.ts @@ -100,4 +100,4 @@ export type SavedAudiobook = { * Information about the audiobook. */ audiobook: SimplifiedAudiobook; -}; \ No newline at end of file +}; diff --git a/endpoints/episode/episode.endpoints.ts b/endpoints/episode/episode.endpoints.ts index 1e4909b..8aeef5d 100644 --- a/endpoints/episode/episode.endpoints.ts +++ b/endpoints/episode/episode.endpoints.ts @@ -86,7 +86,10 @@ export const saveEpisodes = ( * @param client Spotify HTTPClient * @param episodeId The Spotify ID of the episode */ -export const saveEpisode = (client: HTTPClient, episodeId: string): Promise => { +export const saveEpisode = ( + client: HTTPClient, + episodeId: string, +): Promise => { return saveEpisodes(client, [episodeId]); }; diff --git a/endpoints/episode/episode.types.ts b/endpoints/episode/episode.types.ts index 1418547..fdbbf4d 100644 --- a/endpoints/episode/episode.types.ts +++ b/endpoints/episode/episode.types.ts @@ -105,4 +105,4 @@ export type SavedEpisode = { * Information about the episode. */ episode: Episode; -} +}; diff --git a/endpoints/genre/genre.endpoints.ts b/endpoints/genre/genre.endpoints.ts index 4f5a0d4..c58c5a2 100644 --- a/endpoints/genre/genre.endpoints.ts +++ b/endpoints/genre/genre.endpoints.ts @@ -5,7 +5,9 @@ import type { HTTPClient } from "../../client.ts"; * * @param client Spotify HTTPClient */ -export const getAvailableGenreSeeds = async (client: HTTPClient): Promise => { +export const getAvailableGenreSeeds = async ( + client: HTTPClient, +): Promise => { const res = await client.fetch("/v1/recommendations/available-genre-seeds"); return ((await res.json()) as { genres: string[] }).genres; }; diff --git a/endpoints/market/market.endpoints.ts b/endpoints/market/market.endpoints.ts index 34822ef..d35698c 100644 --- a/endpoints/market/market.endpoints.ts +++ b/endpoints/market/market.endpoints.ts @@ -5,7 +5,9 @@ import type { HTTPClient } from "../../client.ts"; * * @param client Spotify HTTPClient */ -export const getAvailableMarkets = async (client: HTTPClient): Promise => { +export const getAvailableMarkets = async ( + client: HTTPClient, +): Promise => { const res = await client.fetch("/v1/markets"); return (await res.json() as { markets: string[] }).markets; }; diff --git a/endpoints/player/player.endpoints.ts b/endpoints/player/player.endpoints.ts index d305d96..dcb7d5d 100644 --- a/endpoints/player/player.endpoints.ts +++ b/endpoints/player/player.endpoints.ts @@ -22,7 +22,8 @@ export type GetPlaybackStateOpts = { /** * Get information about the user’s current playback state, including track or episode, progress, and active device. * - * @requires `user-read-playback-state` + * @requires `user-read-playback-state` \ + * **The user must have a Spotify Premium subscription.** * * @param client Spotify HTTPClient * @param options Additional options for request @@ -58,7 +59,8 @@ export type TransferPlaybackBody = { /** * Transfer playback to a new device and optionally begin playback. The order of execution is not guaranteed when you use this API with other Player API endpoints. * - * @requires `user-modify-playback-state` + * @requires `user-modify-playback-state` \ + * **The user must have a Spotify Premium subscription.** */ export const transferPlayback = ( client: HTTPClient, @@ -70,13 +72,14 @@ export const transferPlayback = ( /** * Get information about a user’s available Spotify Connect devices. Some device models are not supported and will not be listed in the API response. * - * @requires `user-read-playback-state` + * @requires `user-read-playback-state` \ + * **The user must have a Spotify Premium subscription.** */ export const getAvailableDevices = async ( client: HTTPClient, ): Promise => { const res = await client.fetch("/v1/me/player/devices"); - return (await res.json() as { devices: Device[] }).devices; + return ((await res.json()) as { devices: Device[] }).devices; }; export type GetCurrentPlayingTrackOpts = { @@ -93,7 +96,8 @@ export type GetCurrentPlayingTrackOpts = { /** * Get the object currently being played on the user's Spotify account. * - * @requires `user-read-currently-playing` + * @requires `user-read-currently-playing` \ + * **The user must have a Spotify Premium subscription.** */ export const getCurrentPlayingTrack = async ( client: HTTPClient, @@ -149,7 +153,8 @@ export type StartResumePlaybackBody = { /** * Start a new context or resume current playback on the user’s active device. * - * @requires `user-modify-playback-state` + * @requires `user-modify-playback-state` \ + * **The user must have a Spotify Premium subscription.** */ export const startPlayback = ( client: HTTPClient, @@ -166,14 +171,16 @@ export const startPlayback = ( /** * Start a new context or resume current playback on the user’s active device. * - * @requires `user-modify-playback-state` + * @requires `user-modify-playback-state` \ + * **The user must have a Spotify Premium subscription.** */ export const resumePlayback = startPlayback; /** * Pause playback on the user’s account. * - * @requires `user-modify-playback-state` + * @requires `user-modify-playback-state` \ + * **The user must have a Spotify Premium subscription.** * * @param client Spotify HTTPClient * @param deviceId The id of the device this command is targeting. If not supplied, the user's currently active device is the target. @@ -191,7 +198,8 @@ export const pausePlayback = ( /** * Skips to next track in the user’s queue. * - * @requires `user-modify-playback-state` + * @requires `user-modify-playback-state` \ + * **The user must have a Spotify Premium subscription.** * * @param client Spotify HTTPClient * @param deviceId The id of the device this command is targeting. If not supplied, the user's currently active device is the target. @@ -209,7 +217,8 @@ export const skipToNext = ( /** * Skips to previous track in the user’s queue. * - * @requires `user-modify-playback-state` + * @requires `user-modify-playback-state` \ + * **The user must have a Spotify Premium subscription.** * * @param client Spotify HTTPClient * @param deviceId The id of the device this command is targeting. If not supplied, the user's currently active device is the target. @@ -227,7 +236,8 @@ export const skipToPrevious = ( /** * Seeks to the given position in the user’s currently playing track. * - * @requires `user-modify-playback-state` + * @requires `user-modify-playback-state` \ + * **The user must have a Spotify Premium subscription.** * * @param client Spotify HTTPClient * @param positionMs The position in milliseconds to seek to. Must be a positive number. Passing in a position that is greater than the length of the track will cause the player to start playing the next song. @@ -247,7 +257,8 @@ export const seekToPosition = ( /** * Set the repeat mode for the user's playback. * - * @requires `user-modify-playback-state` + * @requires `user-modify-playback-state` \ + * **The user must have a Spotify Premium subscription.** * * @param client Spotify HTTPClient * @param state @@ -270,7 +281,8 @@ export const setRepeatMode = ( /** * Toggle shuffle on or off for user’s playback. * - * @requires `user-modify-playback-state` + * @requires `user-modify-playback-state` \ + * **The user must have a Spotify Premium subscription.** * * @param client Spotify HTTPClient * @param state `true` to turn shuffle on, `false` to turn it off. @@ -308,7 +320,8 @@ export type GetRecentlyPlayedTracksOpts = { /** * Get tracks from the current user's recently played tracks. * - * @requires `user-read-recently-played` + * @requires `user-read-recently-played` \ + * **The user must have a Spotify Premium subscription.** */ export const getRecentPlayedTracks = async ( client: HTTPClient, @@ -323,8 +336,8 @@ export const getRecentPlayedTracks = async ( /** * Get the list of objects that make up the user's queue. * - * @requires `user-read-currently-playing`, -`user-read-playback-state` + * @requires `user-read-currently-playing`, `user-read-playback-state` \ + * **The user must have a Spotify Premium subscription.** */ export const getUserQueue = async (client: HTTPClient): Promise => { const res = await client.fetch("/v1/me/player/queue"); @@ -334,7 +347,8 @@ export const getUserQueue = async (client: HTTPClient): Promise => { /** * Add an item to the end of the user's current playback queue. * - * @requires `user-modify-playback-state` + * @requires `user-modify-playback-state` \ + * **The user must have a Spotify Premium subscription.** * * @param client Spotify HTTPClient * @param uri The uri of the item to add to the queue. Must be a track or an episode uri. diff --git a/tsconfig.json b/tsconfig.json index 2d7cdc8..0d41db1 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -27,4 +27,4 @@ "allowUnusedLabels": false, "skipLibCheck": true } -} \ No newline at end of file +}