/**
 * Lets the global player play a Bandcamp release with its own controls and list
 * a YouTube playlist's tracks. This module types what the Bandcamp and YouTube
 * routes return to it.
 *
 * @module
 */

/** Listed by a {@link Tralbum}, in the release's order. */
export interface TralbumTrack {
  /**
   * The track's position in the release's list. The player keeps it, with the
   * page URL, to resolve the track again once its stream URL expires.
   */
  index: number;
  trackNum?: number;
  title: string;
  /** In seconds, with a fraction. */
  duration?: number;
  /** A signed URL that expires. Null when the track can't be played. */
  streamUrl: string | null;
  /**
   * False for preorder, unreleased and still-encoding tracks. They stay in the
   * list so that the numbering matches the release, but the player skips them.
   */
  streamable: boolean;
  /** Set when Bandcamp capped its free plays, so it may serve only a clip. */
  capped: boolean;
}

/**
 * Returned by `GET /api/bandcamp/tracks` for a Bandcamp album or track page,
 * when the native player plays it.
 */
export interface Tralbum {
  sourceUrl: string;
  itemType: "album" | "track";
  title?: string;
  artist?: string;
  artworkUrl?: string;
  tracks: TralbumTrack[];
  /**
   * When the stream URLs were fetched, in epoch ms. The player resolves the
   * page again once they are old enough to have expired.
   */
  resolvedAt: number;
}

/** Listed by a {@link YouTubePlaylist}, in the playlist's order. */
export interface YouTubePlaylistTrack {
  videoId: string;
  title: string;
  /** In seconds. */
  duration?: number;
}

/**
 * Returned by `GET /api/youtube/playlist` to the player, which shows the
 * titles and lengths of a playlist embed's videos, since the embed exposes
 * neither.
 */
export interface YouTubePlaylist {
  listId: string;
  title?: string;
  tracks: YouTubePlaylistTrack[];
}