spotted-ts 0.1.0

package/src/internal/utils/values.ts

@@ -0,0 +1,105 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { SpottedError } from '../../core/error';
+
+// https://url.spec.whatwg.org/#url-scheme-string
+const startsWithSchemeRegexp = /^[a-z][a-z0-9+.-]*:/i;
+
+export const isAbsoluteURL = (url: string): boolean => {
+  return startsWithSchemeRegexp.test(url);
+};
+
+export let isArray = (val: unknown): val is unknown[] => ((isArray = Array.isArray), isArray(val));
+export let isReadonlyArray = isArray as (val: unknown) => val is readonly unknown[];
+
+/** Returns an object if the given value isn't an object, otherwise returns as-is */
+export function maybeObj(x: unknown): object {
+  if (typeof x !== 'object') {
+    return {};
+  }
+
+  return x ?? {};
+}
+
+// https://stackoverflow.com/a/34491287
+export function isEmptyObj(obj: Object | null | undefined): boolean {
+  if (!obj) return true;
+  for (const _k in obj) return false;
+  return true;
+}
+
+// https://eslint.org/docs/latest/rules/no-prototype-builtins
+export function hasOwn<T extends object = object>(obj: T, key: PropertyKey): key is keyof T {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export function isObj(obj: unknown): obj is Record<string, unknown> {
+  return obj != null && typeof obj === 'object' && !Array.isArray(obj);
+}
+
+export const ensurePresent = <T>(value: T | null | undefined): T => {
+  if (value == null) {
+    throw new SpottedError(`Expected a value to be given but received ${value} instead.`);
+  }
+
+  return value;
+};
+
+export const validatePositiveInteger = (name: string, n: unknown): number => {
+  if (typeof n !== 'number' || !Number.isInteger(n)) {
+    throw new SpottedError(`${name} must be an integer`);
+  }
+  if (n < 0) {
+    throw new SpottedError(`${name} must be a positive integer`);
+  }
+  return n;
+};
+
+export const coerceInteger = (value: unknown): number => {
+  if (typeof value === 'number') return Math.round(value);
+  if (typeof value === 'string') return parseInt(value, 10);
+
+  throw new SpottedError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceFloat = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') return parseFloat(value);
+
+  throw new SpottedError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceBoolean = (value: unknown): boolean => {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') return value === 'true';
+  return Boolean(value);
+};
+
+export const maybeCoerceInteger = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceInteger(value);
+};
+
+export const maybeCoerceFloat = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceFloat(value);
+};
+
+export const maybeCoerceBoolean = (value: unknown): boolean | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceBoolean(value);
+};
+
+export const safeJSON = (text: string) => {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    return undefined;
+  }
+};

package/src/internal/utils.ts

@@ -0,0 +1,8 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './utils/values';
+export * from './utils/base64';
+export * from './utils/env';
+export * from './utils/log';
+export * from './utils/uuid';
+export * from './utils/sleep';

package/src/lib/.keep

@@ -0,0 +1,4 @@
+File generated from our OpenAPI spec by Stainless.
+
+This directory can be used to store custom files to expand the SDK.
+It is ignored by Stainless code generation and its content (other than this keep file) won't be touched.

package/src/pagination.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';

package/src/resource.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/resource instead */
+export * from './core/resource';

package/src/resources/albums.ts

@@ -0,0 +1,427 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import * as Shared from './shared';
+import { SimplifiedTrackObjectsCursorURLPage } from './shared';
+import { APIPromise } from '../core/api-promise';
+import { CursorURLPage, PagePromise } from '../core/pagination';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Albums extends APIResource {
+  /**
+   * Get Spotify catalog information for a single album.
+   */
+  retrieve(
+    id: string,
+    query: AlbumRetrieveParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<AlbumRetrieveResponse> {
+    return this._client.get(path`/albums/${id}`, { query, ...options });
+  }
+
+  /**
+   * Get Spotify catalog information for multiple albums identified by their Spotify
+   * IDs.
+   */
+  bulkRetrieve(
+    query: AlbumBulkRetrieveParams,
+    options?: RequestOptions,
+  ): APIPromise<AlbumBulkRetrieveResponse> {
+    return this._client.get('/albums', { query, ...options });
+  }
+
+  /**
+   * Get Spotify catalog information about an album’s tracks. Optional parameters can
+   * be used to limit the number of tracks returned.
+   */
+  listTracks(
+    id: string,
+    query: AlbumListTracksParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<SimplifiedTrackObjectsCursorURLPage, Shared.SimplifiedTrackObject> {
+    return this._client.getAPIList(path`/albums/${id}/tracks`, CursorURLPage<Shared.SimplifiedTrackObject>, {
+      query,
+      ...options,
+    });
+  }
+}
+
+export interface AlbumRetrieveResponse {
+  /**
+   * The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) for the
+   * album.
+   */
+  id: string;
+
+  /**
+   * The type of the album.
+   */
+  album_type: 'album' | 'single' | 'compilation';
+
+  /**
+   * The markets in which the album is available:
+   * [ISO 3166-1 alpha-2 country codes](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
+   * _**NOTE**: an album is considered available in a market when at least 1 of its
+   * tracks is available in that market._
+   */
+  available_markets: Array<string>;
+
+  /**
+   * Known external URLs for this album.
+   */
+  external_urls: Shared.ExternalURLObject;
+
+  /**
+   * A link to the Web API endpoint providing full details of the album.
+   */
+  href: string;
+
+  /**
+   * The cover art for the album in various sizes, widest first.
+   */
+  images: Array<Shared.ImageObject>;
+
+  /**
+   * The name of the album. In case of an album takedown, the value may be an empty
+   * string.
+   */
+  name: string;
+
+  /**
+   * The date the album was first released.
+   */
+  release_date: string;
+
+  /**
+   * The precision with which `release_date` value is known.
+   */
+  release_date_precision: 'year' | 'month' | 'day';
+
+  /**
+   * The number of tracks in the album.
+   */
+  total_tracks: number;
+
+  /**
+   * The object type.
+   */
+  type: 'album';
+
+  /**
+   * The [Spotify URI](/documentation/web-api/concepts/spotify-uris-ids) for the
+   * album.
+   */
+  uri: string;
+
+  /**
+   * The artists of the album. Each artist object includes a link in `href` to more
+   * detailed information about the artist.
+   */
+  artists?: Array<Shared.SimplifiedArtistObject>;
+
+  /**
+   * The copyright statements of the album.
+   */
+  copyrights?: Array<Shared.CopyrightObject>;
+
+  /**
+   * Known external IDs for the album.
+   */
+  external_ids?: Shared.ExternalIDObject;
+
+  /**
+   * @deprecated **Deprecated** The array is always empty.
+   */
+  genres?: Array<string>;
+
+  /**
+   * The label associated with the album.
+   */
+  label?: string;
+
+  /**
+   * The popularity of the album. The value will be between 0 and 100, with 100 being
+   * the most popular.
+   */
+  popularity?: number;
+
+  /**
+   * Included in the response when a content restriction is applied.
+   */
+  restrictions?: Shared.AlbumRestrictionObject;
+
+  /**
+   * The tracks of the album.
+   */
+  tracks?: AlbumRetrieveResponse.Tracks;
+}
+
+export namespace AlbumRetrieveResponse {
+  /**
+   * The tracks of the album.
+   */
+  export interface Tracks {
+    /**
+     * A link to the Web API endpoint returning the full result of the request
+     */
+    href: string;
+
+    items: Array<Shared.SimplifiedTrackObject>;
+
+    /**
+     * The maximum number of items in the response (as set in the query or by default).
+     */
+    limit: number;
+
+    /**
+     * URL to the next page of items. ( `null` if none)
+     */
+    next: string | null;
+
+    /**
+     * The offset of the items returned (as set in the query or by default)
+     */
+    offset: number;
+
+    /**
+     * URL to the previous page of items. ( `null` if none)
+     */
+    previous: string | null;
+
+    /**
+     * The total number of items available to return.
+     */
+    total: number;
+  }
+}
+
+export interface AlbumBulkRetrieveResponse {
+  albums: Array<AlbumBulkRetrieveResponse.Album>;
+}
+
+export namespace AlbumBulkRetrieveResponse {
+  export interface Album {
+    /**
+     * The [Spotify ID](/documentation/web-api/concepts/spotify-uris-ids) for the
+     * album.
+     */
+    id: string;
+
+    /**
+     * The type of the album.
+     */
+    album_type: 'album' | 'single' | 'compilation';
+
+    /**
+     * The markets in which the album is available:
+     * [ISO 3166-1 alpha-2 country codes](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
+     * _**NOTE**: an album is considered available in a market when at least 1 of its
+     * tracks is available in that market._
+     */
+    available_markets: Array<string>;
+
+    /**
+     * Known external URLs for this album.
+     */
+    external_urls: Shared.ExternalURLObject;
+
+    /**
+     * A link to the Web API endpoint providing full details of the album.
+     */
+    href: string;
+
+    /**
+     * The cover art for the album in various sizes, widest first.
+     */
+    images: Array<Shared.ImageObject>;
+
+    /**
+     * The name of the album. In case of an album takedown, the value may be an empty
+     * string.
+     */
+    name: string;
+
+    /**
+     * The date the album was first released.
+     */
+    release_date: string;
+
+    /**
+     * The precision with which `release_date` value is known.
+     */
+    release_date_precision: 'year' | 'month' | 'day';
+
+    /**
+     * The number of tracks in the album.
+     */
+    total_tracks: number;
+
+    /**
+     * The object type.
+     */
+    type: 'album';
+
+    /**
+     * The [Spotify URI](/documentation/web-api/concepts/spotify-uris-ids) for the
+     * album.
+     */
+    uri: string;
+
+    /**
+     * The artists of the album. Each artist object includes a link in `href` to more
+     * detailed information about the artist.
+     */
+    artists?: Array<Shared.SimplifiedArtistObject>;
+
+    /**
+     * The copyright statements of the album.
+     */
+    copyrights?: Array<Shared.CopyrightObject>;
+
+    /**
+     * Known external IDs for the album.
+     */
+    external_ids?: Shared.ExternalIDObject;
+
+    /**
+     * @deprecated **Deprecated** The array is always empty.
+     */
+    genres?: Array<string>;
+
+    /**
+     * The label associated with the album.
+     */
+    label?: string;
+
+    /**
+     * The popularity of the album. The value will be between 0 and 100, with 100 being
+     * the most popular.
+     */
+    popularity?: number;
+
+    /**
+     * Included in the response when a content restriction is applied.
+     */
+    restrictions?: Shared.AlbumRestrictionObject;
+
+    /**
+     * The tracks of the album.
+     */
+    tracks?: Album.Tracks;
+  }
+
+  export namespace Album {
+    /**
+     * The tracks of the album.
+     */
+    export interface Tracks {
+      /**
+       * A link to the Web API endpoint returning the full result of the request
+       */
+      href: string;
+
+      items: Array<Shared.SimplifiedTrackObject>;
+
+      /**
+       * The maximum number of items in the response (as set in the query or by default).
+       */
+      limit: number;
+
+      /**
+       * URL to the next page of items. ( `null` if none)
+       */
+      next: string | null;
+
+      /**
+       * The offset of the items returned (as set in the query or by default)
+       */
+      offset: number;
+
+      /**
+       * URL to the previous page of items. ( `null` if none)
+       */
+      previous: string | null;
+
+      /**
+       * The total number of items available to return.
+       */
+      total: number;
+    }
+  }
+}
+
+export interface AlbumRetrieveParams {
+  /**
+   * 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;
+}
+
+export interface AlbumBulkRetrieveParams {
+  /**
+   * A comma-separated list of the
+   * [Spotify IDs](/documentation/web-api/concepts/spotify-uris-ids) for the albums.
+   * Maximum: 20 IDs.
+   */
+  ids: string;
+
+  /**
+   * 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;
+}
+
+export interface AlbumListTracksParams {
+  /**
+   * 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 declare namespace Albums {
+  export {
+    type AlbumRetrieveResponse as AlbumRetrieveResponse,
+    type AlbumBulkRetrieveResponse as AlbumBulkRetrieveResponse,
+    type AlbumRetrieveParams as AlbumRetrieveParams,
+    type AlbumBulkRetrieveParams as AlbumBulkRetrieveParams,
+    type AlbumListTracksParams as AlbumListTracksParams,
+  };
+}
+
+export { type SimplifiedTrackObjectsCursorURLPage };