spotify-types/typings/global.d.ts

All the typings for the various Spotify API Object typings written in typescript.

import { Artist } from "./artist";
import { Track } from "./track";
import { SimplifiedAlbum } from "./album";
import { SimplifiedEpisode } from "./episode";
import { SimplifiedShow } from "./show";

/**
 * All the spotify element types
 */
export type SpotifyType = 'user' | 'episode' | 'playlist' | 'show' | 'track' | 'album' | 'artist';

/**
 * All the spotify search types.
 */
export type SearchType = 'album' | 'artist' | 'track' |  'show' | 'episode';

/**
 * The spotify object containing the details of an image.
 * 
 * @see https://developer.spotify.com/documentation/web-api/reference/#object-imageobject
 */
export interface Image {
    /** The image height in pixels. If unknown: null or not returned. */
    height: number | null;
    /** The source URL of the image. */
    url: string;
    /** The image width in pixels. If unknown: null or not returned. */
    width: number | null;
}

/**
 * The external urls object which contains the spotify url within it.
 * 
 * @see https://developer.spotify.com/documentation/web-api/reference/#object-externalurlobject
 */
export interface ExternalUrl {
    /** The Spotify URL for the object. */
    spotify: string;
}

/**
 * The external ids object which contains the spotify id within it.
 * 
 * @see https://developer.spotify.com/documentation/web-api/reference/#object-externalidobject
 */
export interface ExternalID {
    /** International Article Number */
    ean: string;
    /** International Standard Recording Code */
    isrc: string;
    /** Universal Product Code */
    upc: string;
}

/**
 * The paging object is a form of collection of items from the spotify api.
 * 
 * @see https://developer.spotify.com/documentation/web-api/reference/#object-pagingobject
 */
export interface Paging<T> {
    /** A link to the Web API endpoint returning the full result of the request. */
    href: string;
    /** The requested data. */
    items: T[];
    /** 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;
    /** 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;
    /** The total number of items available to return. */
    total: number;
}

/**
 * The copyright object contains the type and the name of copyright.
 * 
 * @see https://developer.spotify.com/documentation/web-api/reference/#object-copyrightobject
 */
export interface Copyright {
    /** The text of copyright. */
    text: string;
    /** The type of copyright. */
    type: 'C' | 'P';
}

/**
 * The object containing the reason of restriction by the spotify api.
 */
export interface Restriction {
    /** The reason for the restriction. */
    reason: 'market' | 'product' | 'explicit';
}

/**
 * The error response sent by the spotify api during unusual status codes.
 * 
 * @see https://developer.spotify.com/documentation/web-api/reference/#object-errorobject
 */
export interface ErrorResponse {
    /** A short description of the cause of the error. */
    message: string;
    /** The HTTP status code (also returned in the response header; see Response Status Codes for more information). */
    status: number;
}

/**
 * The object containing the saved elements and the timestamp when they were added.
 */
export type Saved<K extends SpotifyType, T> = { added_at: string } & Record<K, T>;

/** 
 * The object structure returned by the [/search] endpoint.
 */
export interface SearchContent {
    /** The episode search results. */
    episodes?: Paging<SimplifiedEpisode>;
    /** The show search results. */
    shows?: Paging<SimplifiedShow>;
    /** The track search results. */
    tracks?: Paging<Track>;
    /** The artists search results. */
    artists?: Paging<Artist>;
    /** the album search results. */
    albums?: Paging<SimplifiedAlbum>;
}