spotted-ts 0.1.0

package/src/resources/me/player/queue.ts

@@ -0,0 +1,71 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as Shared from '../../shared';
+import { APIPromise } from '../../../core/api-promise';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+
+export class Queue extends APIResource {
+  /**
+   * Add an item to be played next in the user's current playback queue. This API
+   * only works for users who have Spotify Premium. The order of execution is not
+   * guaranteed when you use this API with other Player API endpoints.
+   *
+   * @example
+   * ```ts
+   * await client.me.player.queue.add({
+   *   uri: 'spotify:track:4iV5W9uYEdYUVa79Axb7Rh',
+   * });
+   * ```
+   */
+  add(params: QueueAddParams, options?: RequestOptions): APIPromise<void> {
+    const { uri, device_id } = params;
+    return this._client.post('/me/player/queue', {
+      query: { uri, device_id },
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Get the list of objects that make up the user's queue.
+   *
+   * @example
+   * ```ts
+   * const queue = await client.me.player.queue.get();
+   * ```
+   */
+  get(options?: RequestOptions): APIPromise<QueueGetResponse> {
+    return this._client.get('/me/player/queue', options);
+  }
+}
+
+export interface QueueGetResponse {
+  /**
+   * The currently playing track or episode. Can be `null`.
+   */
+  currently_playing?: Shared.TrackObject | Shared.EpisodeObject;
+
+  /**
+   * The tracks or episodes in the queue. Can be empty.
+   */
+  queue?: Array<Shared.TrackObject | Shared.EpisodeObject>;
+}
+
+export interface QueueAddParams {
+  /**
+   * The uri of the item to add to the queue. Must be a track or an episode uri.
+   */
+  uri: string;
+
+  /**
+   * The id of the device this command is targeting. If not supplied, the user's
+   * currently active device is the target.
+   */
+  device_id?: string;
+}
+
+export declare namespace Queue {
+  export { type QueueGetResponse as QueueGetResponse, type QueueAddParams as QueueAddParams };
+}

package/src/resources/me/player.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './player/index';

package/src/resources/me/playlists.ts

@@ -0,0 +1,49 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
+import { SimplifiedPlaylistObjectsCursorURLPage } from '../shared';
+import { CursorURLPage, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+
+export class Playlists extends APIResource {
+  /**
+   * Get a list of the playlists owned or followed by the current Spotify user.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const simplifiedPlaylistObject of client.me.playlists.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: PlaylistListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<SimplifiedPlaylistObjectsCursorURLPage, Shared.SimplifiedPlaylistObject> {
+    return this._client.getAPIList('/me/playlists', CursorURLPage<Shared.SimplifiedPlaylistObject>, {
+      query,
+      ...options,
+    });
+  }
+}
+
+export interface PlaylistListParams {
+  /**
+   * The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
+   */
+  limit?: number;
+
+  /**
+   * 'The index of the first playlist to return. Default: 0 (the first object).
+   * Maximum offset: 100.000\. Use with `limit` to get the next set of playlists.'
+   */
+  offset?: number;
+}
+
+export declare namespace Playlists {
+  export { type PlaylistListParams as PlaylistListParams };
+}
+
+export { type SimplifiedPlaylistObjectsCursorURLPage };

package/src/resources/me/shows.ts

@@ -0,0 +1,152 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
+import { APIPromise } from '../../core/api-promise';
+import { CursorURLPage, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+
+export class Shows extends APIResource {
+  /**
+   * Get a list of shows saved in the current Spotify user's library. Optional
+   * parameters can be used to limit the number of shows returned.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const showListResponse of client.me.shows.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: ShowListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<ShowListResponsesCursorURLPage, ShowListResponse> {
+    return this._client.getAPIList('/me/shows', CursorURLPage<ShowListResponse>, { query, ...options });
+  }
+
+  /**
+   * Check if one or more shows is already saved in the current Spotify user's
+   * library.
+   *
+   * @example
+   * ```ts
+   * const response = await client.me.shows.check({
+   *   ids: '5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ',
+   * });
+   * ```
+   */
+  check(query: ShowCheckParams, options?: RequestOptions): APIPromise<ShowCheckResponse> {
+    return this._client.get('/me/shows/contains', { query, ...options });
+  }
+
+  /**
+   * Delete one or more shows from current Spotify user's library.
+   *
+   * @example
+   * ```ts
+   * await client.me.shows.remove();
+   * ```
+   */
+  remove(body: ShowRemoveParams | null | undefined = {}, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete('/me/shows', {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Save one or more shows to current Spotify user's library.
+   *
+   * @example
+   * ```ts
+   * await client.me.shows.save();
+   * ```
+   */
+  save(body: ShowSaveParams | null | undefined = {}, options?: RequestOptions): APIPromise<void> {
+    return this._client.put('/me/shows', {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type ShowListResponsesCursorURLPage = CursorURLPage<ShowListResponse>;
+
+export interface ShowListResponse {
+  /**
+   * The date and time the show was saved. Timestamps are returned in ISO 8601 format
+   * as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ. If
+   * the time is imprecise (for example, the date/time of an album release), an
+   * additional field indicates the precision; see for example, release_date in an
+   * album object.
+   */
+  added_at?: string;
+
+  /**
+   * Information about the show.
+   */
+  show?: Shared.ShowBase;
+}
+
+export type ShowCheckResponse = Array<boolean>;
+
+export interface ShowListParams {
+  /**
+   * The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
+   */
+  limit?: number;
+
+  /**
+   * The index of the first item to return. Default: 0 (the first item). Use with
+   * limit to get the next set of items.
+   */
+  offset?: number;
+}
+
+export interface ShowCheckParams {
+  /**
+   * A comma-separated list of the
+   * [Spotify IDs](/documentation/web-api/concepts/spotify-uris-ids) for the shows.
+   * Maximum: 50 IDs.
+   */
+  ids: string;
+}
+
+export interface ShowRemoveParams {
+  /**
+   * A JSON array of the
+   * [Spotify IDs](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids).
+   * A maximum of 50 items can be specified in one request. _Note: if the `ids`
+   * parameter is present in the query string, any IDs listed here in the body will
+   * be ignored._
+   */
+  ids?: Array<string>;
+}
+
+export interface ShowSaveParams {
+  /**
+   * A JSON array of the
+   * [Spotify IDs](https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids).
+   * A maximum of 50 items can be specified in one request. _Note: if the `ids`
+   * parameter is present in the query string, any IDs listed here in the body will
+   * be ignored._
+   */
+  ids?: Array<string>;
+}
+
+export declare namespace Shows {
+  export {
+    type ShowListResponse as ShowListResponse,
+    type ShowCheckResponse as ShowCheckResponse,
+    type ShowListResponsesCursorURLPage as ShowListResponsesCursorURLPage,
+    type ShowListParams as ShowListParams,
+    type ShowCheckParams as ShowCheckParams,
+    type ShowRemoveParams as ShowRemoveParams,
+    type ShowSaveParams as ShowSaveParams,
+  };
+}

package/src/resources/me/top.ts

@@ -0,0 +1,102 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
+import { ArtistObjectsCursorURLPage, TrackObjectsCursorURLPage } from '../shared';
+import { CursorURLPage, PagePromise } from '../../core/pagination';
+import { RequestOptions } from '../../internal/request-options';
+
+export class Top extends APIResource {
+  /**
+   * Get the current user's top artists based on calculated affinity.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const artistObject of client.me.top.listTopArtists()) {
+   *   // ...
+   * }
+   * ```
+   */
+  listTopArtists(
+    query: TopListTopArtistsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<ArtistObjectsCursorURLPage, Shared.ArtistObject> {
+    return this._client.getAPIList('/me/top/artists', CursorURLPage<Shared.ArtistObject>, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Get the current user's top tracks based on calculated affinity.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const trackObject of client.me.top.listTopTracks()) {
+   *   // ...
+   * }
+   * ```
+   */
+  listTopTracks(
+    query: TopListTopTracksParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<TrackObjectsCursorURLPage, Shared.TrackObject> {
+    return this._client.getAPIList('/me/top/tracks', CursorURLPage<Shared.TrackObject>, {
+      query,
+      ...options,
+    });
+  }
+}
+
+export interface TopListTopArtistsParams {
+  /**
+   * The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
+   */
+  limit?: number;
+
+  /**
+   * The index of the first item to return. Default: 0 (the first item). Use with
+   * limit to get the next set of items.
+   */
+  offset?: number;
+
+  /**
+   * Over what time frame the affinities are computed. Valid values: `long_term`
+   * (calculated from ~1 year of data and including all new data as it becomes
+   * available), `medium_term` (approximately last 6 months), `short_term`
+   * (approximately last 4 weeks). Default: `medium_term`
+   */
+  time_range?: string;
+}
+
+export interface TopListTopTracksParams {
+  /**
+   * The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
+   */
+  limit?: number;
+
+  /**
+   * The index of the first item to return. Default: 0 (the first item). Use with
+   * limit to get the next set of items.
+   */
+  offset?: number;
+
+  /**
+   * Over what time frame the affinities are computed. Valid values: `long_term`
+   * (calculated from ~1 year of data and including all new data as it becomes
+   * available), `medium_term` (approximately last 6 months), `short_term`
+   * (approximately last 4 weeks). Default: `medium_term`
+   */
+  time_range?: string;
+}
+
+export declare namespace Top {
+  export {
+    type TopListTopArtistsParams as TopListTopArtistsParams,
+    type TopListTopTracksParams as TopListTopTracksParams,
+  };
+}
+
+export { type ArtistObjectsCursorURLPage, type TrackObjectsCursorURLPage };

package/src/resources/me/tracks.ts

@@ -0,0 +1,200 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as Shared from '../shared';
+import { APIPromise } from '../../core/api-promise';
+import { CursorURLPage, PagePromise } from '../../core/pagination';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+
+export class Tracks extends APIResource {
+  /**
+   * Get a list of the songs saved in the current Spotify user's 'Your Music'
+   * library.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const trackListResponse of client.me.tracks.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: TrackListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<TrackListResponsesCursorURLPage, TrackListResponse> {
+    return this._client.getAPIList('/me/tracks', CursorURLPage<TrackListResponse>, { query, ...options });
+  }
+
+  /**
+   * Check if one or more tracks is already saved in the current Spotify user's 'Your
+   * Music' library.
+   *
+   * @example
+   * ```ts
+   * const response = await client.me.tracks.check({
+   *   ids: '7ouMYWpwJ422jRcDASZB7P,4VqPOruhp5EdPBeR92t6lQ,2takcwOaAZWiXQijPHIx7B',
+   * });
+   * ```
+   */
+  check(query: TrackCheckParams, options?: RequestOptions): APIPromise<TrackCheckResponse> {
+    return this._client.get('/me/tracks/contains', { query, ...options });
+  }
+
+  /**
+   * Remove one or more tracks from the current user's 'Your Music' library.
+   *
+   * @example
+   * ```ts
+   * await client.me.tracks.remove();
+   * ```
+   */
+  remove(body: TrackRemoveParams | null | undefined = {}, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete('/me/tracks', {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Save one or more tracks to the current user's 'Your Music' library.
+   *
+   * @example
+   * ```ts
+   * await client.me.tracks.save({ ids: ['string'] });
+   * ```
+   */
+  save(body: TrackSaveParams, options?: RequestOptions): APIPromise<void> {
+    return this._client.put('/me/tracks', {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type TrackListResponsesCursorURLPage = CursorURLPage<TrackListResponse>;
+
+export interface TrackListResponse {
+  /**
+   * The date and time the track was saved. Timestamps are returned in ISO 8601
+   * format as Coordinated Universal Time (UTC) with a zero offset:
+   * YYYY-MM-DDTHH:MM:SSZ. If the time is imprecise (for example, the date/time of an
+   * album release), an additional field indicates the precision; see for example,
+   * release_date in an album object.
+   */
+  added_at?: string;
+
+  /**
+   * Information about the track.
+   */
+  track?: Shared.TrackObject;
+}
+
+export type TrackCheckResponse = Array<boolean>;
+
+export interface TrackListParams {
+  /**
+   * The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
+   */
+  limit?: number;
+
+  /**
+   * An
+   * [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
+   * If a country code is specified, only content that is available in that market
+   * will be returned.<br/> If a valid user access token is specified in the request
+   * header, the country associated with the user account will take priority over
+   * this parameter.<br/> _**Note**: If neither market or user country are provided,
+   * the content is considered unavailable for the client._<br/> Users can view the
+   * country that is associated with their account in the
+   * [account settings](https://www.spotify.com/account/overview/).
+   */
+  market?: string;
+
+  /**
+   * The index of the first item to return. Default: 0 (the first item). Use with
+   * limit to get the next set of items.
+   */
+  offset?: number;
+}
+
+export interface TrackCheckParams {
+  /**
+   * A comma-separated list of the
+   * [Spotify IDs](/documentation/web-api/concepts/spotify-uris-ids). For example:
+   * `ids=4iV5W9uYEdYUVa79Axb7Rh,1301WleyT98MSxVHPZCA6M`. Maximum: 50 IDs.
+   */
+  ids: string;
+}
+
+export interface TrackRemoveParams {
+  /**
+   * A JSON array of the
+   * [Spotify IDs](/documentation/web-api/concepts/spotify-uris-ids). For example:
+   * `["4iV5W9uYEdYUVa79Axb7Rh", "1301WleyT98MSxVHPZCA6M"]`<br/>A maximum of 50 items
+   * can be specified in one request. _**Note**: if the `ids` parameter is present in
+   * the query string, any IDs listed here in the body will be ignored._
+   */
+  ids?: Array<string>;
+
+  [k: string]: unknown;
+}
+
+export interface TrackSaveParams {
+  /**
+   * A JSON array of the
+   * [Spotify IDs](/documentation/web-api/concepts/spotify-uris-ids). For example:
+   * `["4iV5W9uYEdYUVa79Axb7Rh", "1301WleyT98MSxVHPZCA6M"]`<br/>A maximum of 50 items
+   * can be specified in one request. _**Note**: if the `timestamped_ids` is present
+   * in the body, any IDs listed in the query parameters (deprecated) or the `ids`
+   * field in the body will be ignored._
+   */
+  ids: Array<string>;
+
+  /**
+   * A JSON array of objects containing track IDs with their corresponding
+   * timestamps. Each object must include a track ID and an `added_at` timestamp.
+   * This allows you to specify when tracks were added to maintain a specific
+   * chronological order in the user's library.<br/>A maximum of 50 items can be
+   * specified in one request. _**Note**: if the `timestamped_ids` is present in the
+   * body, any IDs listed in the query parameters (deprecated) or the `ids` field in
+   * the body will be ignored._
+   */
+  timestamped_ids?: Array<TrackSaveParams.TimestampedID>;
+
+  [k: string]: unknown;
+}
+
+export namespace TrackSaveParams {
+  export interface TimestampedID {
+    /**
+     * The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) for the
+     * track.
+     */
+    id: string;
+
+    /**
+     * The timestamp when the track was added to the library. Use ISO 8601 format with
+     * UTC timezone (e.g., `2023-01-15T14:30:00Z`). You can specify past timestamps to
+     * insert tracks at specific positions in the library's chronological order. The
+     * API uses minute-level granularity for ordering, though the timestamp supports
+     * millisecond precision.
+     */
+    added_at: string;
+  }
+}
+
+export declare namespace Tracks {
+  export {
+    type TrackListResponse as TrackListResponse,
+    type TrackCheckResponse as TrackCheckResponse,
+    type TrackListResponsesCursorURLPage as TrackListResponsesCursorURLPage,
+    type TrackListParams as TrackListParams,
+    type TrackCheckParams as TrackCheckParams,
+    type TrackRemoveParams as TrackRemoveParams,
+    type TrackSaveParams as TrackSaveParams,
+  };
+}

package/src/resources/me.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './me/index';

package/src/resources/playlists/followers.ts

@@ -0,0 +1,97 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Followers extends APIResource {
+  /**
+   * Check to see if the current user is following a specified playlist.
+   *
+   * @example
+   * ```ts
+   * const response = await client.playlists.followers.check(
+   *   '3cEYpjA9oz9GiPac4AsH4n',
+   * );
+   * ```
+   */
+  check(
+    playlistID: string,
+    query: FollowerCheckParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<FollowerCheckResponse> {
+    return this._client.get(path`/playlists/${playlistID}/followers/contains`, { query, ...options });
+  }
+
+  /**
+   * Add the current user as a follower of a playlist.
+   *
+   * @example
+   * ```ts
+   * await client.playlists.followers.follow(
+   *   '3cEYpjA9oz9GiPac4AsH4n',
+   * );
+   * ```
+   */
+  follow(
+    playlistID: string,
+    body: FollowerFollowParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    return this._client.put(path`/playlists/${playlistID}/followers`, {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Remove the current user as a follower of a playlist.
+   *
+   * @example
+   * ```ts
+   * await client.playlists.followers.unfollow(
+   *   '3cEYpjA9oz9GiPac4AsH4n',
+   * );
+   * ```
+   */
+  unfollow(playlistID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/playlists/${playlistID}/followers`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type FollowerCheckResponse = Array<boolean>;
+
+export interface FollowerCheckParams {
+  /**
+   * **Deprecated** A single item list containing current user's
+   * [Spotify Username](/documentation/web-api/concepts/spotify-uris-ids). Maximum: 1
+   * id.
+   */
+  ids?: string;
+}
+
+export interface FollowerFollowParams {
+  /**
+   * Defaults to `true`. If `true` the playlist will be included in user's public
+   * playlists (added to profile), if `false` it will remain private. For more about
+   * public/private status, see
+   * [Working with Playlists](/documentation/web-api/concepts/playlists)
+   */
+  public?: boolean;
+
+  [k: string]: unknown;
+}
+
+export declare namespace Followers {
+  export {
+    type FollowerCheckResponse as FollowerCheckResponse,
+    type FollowerCheckParams as FollowerCheckParams,
+    type FollowerFollowParams as FollowerFollowParams,
+  };
+}