javascript-ampache 1.0.8 → 1.1.0

package/src/songs/index.ts

@@ -1,203 +1,208 @@
-import qs from 'querystringify';
-import { Song, DeletedSong } from './types';
-import {Base, BinaryBoolean, ExtendedPagination, Pagination, Success, UID} from '../base';
-
-export class Songs extends Base {
-    /**
-     * Returns songs based on the specified filter
-     * @remarks MINIMUM_API_VERSION=380001
-     * @param [params.filter] Filter results to match this string
-     * @param [params.exact] 0, 1 (if true filter is exact = rather than fuzzy LIKE)
-     * @param [params.add] ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date
-     * @param [params.update] ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date
-     * @param [params.offset]
-     * @param [params.limit]
-     * @param [params.cond]
-     * @param [params.sort]
-     * @see {@link https://ampache.org/api/api-json-methods#songs}
-     */
-    async songs (params?: {
-        filter?: string,
-        exact?: BinaryBoolean,
-        add?: Date,
-        update?: Date,
-    } & ExtendedPagination) {
-        let query = 'songs';
-        query += qs.stringify(params, '&');
-        let data = await this.request<{song: Song[]}>(query);
-        return (data.song) ? data.song : data;
-    }
-
-    /**
-     * Returns a single song
-     * @remarks MINIMUM_API_VERSION=380001
-     * @param params.filter UID to find
-     * @see {@link https://ampache.org/api/api-json-methods#song}
-     */
-    song (params: {
-        filter: UID,
-    }) {
-        let query = 'song';
-        query += qs.stringify(params, '&');
-        return this.request<Song>(query);
-    }
-
-    /**
-     * Songs of the specified artist
-     * @remarks MINIMUM_API_VERSION=380001
-     * @param params.filter UID to find
-     * @param [params.top50] 0, 1 (if true filter to the artist top 50)
-     * @param [params.offset]
-     * @param [params.limit]
-     * @param [params.cond]
-     * @param [params.sort]
-     * @see {@link https://ampache.org/api/api-json-methods#artist_songs}
-     */
-    async artistSongs (params: {
-        filter: UID,
-        top50?: BinaryBoolean,
-    } & ExtendedPagination) {
-        let query = 'artist_songs';
-        query += qs.stringify(params, '&');
-        let data = await this.request<{song: Song[]}>(query);
-        return (data.song) ? data.song : data;
-    }
-
-    /**
-     * Songs of the specified album
-     * @remarks MINIMUM_API_VERSION=380001
-     * @param params.filter UID to find
-     * @param [params.offset]
-     * @param [params.limit]
-     * @param [params.cond]
-     * @param [params.sort]
-     * @see {@link https://ampache.org/api/api-json-methods#album_songs}
-     */
-    async albumSongs (params: {
-        filter: UID,
-    } & ExtendedPagination) {
-        let query = 'album_songs';
-        query += qs.stringify(params, '&');
-        let data = await this.request<{song: Song[]}>(query);
-        return (data.song) ? data.song : data;
-    }
-
-    /**
-     * Songs of the specified genre
-     * @remarks MINIMUM_API_VERSION=380001
-     * @param params.filter UID to find
-     * @param [params.offset]
-     * @param [params.limit]
-     * @param [params.cond]
-     * @param [params.sort]
-     * @see {@link https://ampache.org/api/api-json-methods#genre_songs}
-     */
-    async genreSongs (params: {
-        filter: UID,
-    } & ExtendedPagination) {
-        let query = 'genre_songs';
-        query += qs.stringify(params, '&');
-        let data = await this.request<{song: Song[]}>(query);
-        return (data.song) ? data.song : data;
-    }
-
-    /**
-     * This returns the songs for a playlist
-     * @remarks MINIMUM_API_VERSION=380001
-     * @param params.filter UID to find
-     * @param [params.random] 0, 1 (if true get random songs using limit)
-     * @param [params.offset]
-     * @param [params.limit]
-     * @see {@link https://ampache.org/api/api-json-methods#playlist_songs}
-     */
-    async playlistSongs (params: {
-        filter: UID,
-        random?: BinaryBoolean,
-    } & Pagination) {
-        let query = 'playlist_songs';
-        query += qs.stringify(params, '&');
-        let data = await this.request<{song: Song[]}>(query);
-        return (data.song) ? data.song : data;
-    }
-
-    /**
-     * This returns the songs for a license
-     * @remarks MINIMUM_API_VERSION=420000
-     * @param params.filter UID to find
-     * @param [params.offset]
-     * @param [params.limit]
-     * @param [params.cond]
-     * @param [params.sort]
-     * @see {@link https://ampache.org/api/api-json-methods#license_songs}
-     */
-    async licenseSongs (params: {
-        filter: UID,
-    } & ExtendedPagination) {
-        let query = 'license_songs';
-        query += qs.stringify(params, '&');
-        let data = await this.request<{song: Song[]}>(query);
-        return (data.song) ? data.song : data;
-    }
-
-    /**
-     * Delete an existing song. (if you are allowed to)
-     * @remarks MINIMUM_API_VERSION=5.0.0
-     * @param params.filter UID of song to delete
-     * @see {@link https://ampache.org/api/api-json-methods#song_delete}
-     */
-    songDelete (params: {
-        filter: UID,
-    }) {
-        let query = 'song_delete';
-        query += qs.stringify(params, '&');
-        return this.request<Success>(query);
-    }
-
-    /**
-     * This takes a URL and returns the song object in question
-     * @remarks MINIMUM_API_VERSION=380001
-     * @param params.url Full Ampache URL from server
-     * @see {@link https://ampache.org/api/api-json-methods#url_to_song}
-     */
-    urlToSong (params: {
-        url: string,
-    }) {
-        let query = 'url_to_song';
-        params.url = encodeURIComponent(params.url);
-        query += qs.stringify(params, '&');
-        return this.request<Song>(query);
-    }
-
-    /**
-     * This searches the songs and returns... songs
-     * @remarks MINIMUM_API_VERSION=380001
-     * @param params.filter Filter results to match this string
-     * @param [params.offset]
-     * @param [params.limit]
-     * @see {@link https://ampache.org/api/api-json-methods#search_songs}
-     */
-    async searchSongs (params: {
-        filter: string,
-    } & Pagination) {
-        let query = 'search_songs';
-        query += qs.stringify(params, '&');
-        let data = await this.request<{song: Song[]}>(query);
-        return (data.song) ? data.song : data;
-    }
-
-    /**
-     * Returns songs that have been deleted from the server
-     * @remarks MINIMUM_API_VERSION=500000
-     * @param [params.offset]
-     * @param [params.limit]
-     * @see {@link https://ampache.org/api/api-json-methods#deleted_songs}
-     */
-    async deletedSongs (params?: {
-
-    } & Pagination) {
-        let query = 'deleted_songs';
-        query += qs.stringify(params, '&');
-        let data = await this.request<{deleted_song: DeletedSong[]}>(query);
-        return (data.deleted_song) ? data.deleted_song : data;
-    }
-}
+import qs from "querystringify";
+import { SongResponse, SongsResponse, DeletedSongsResponse } from "./types";
+import {
+  Base,
+  BinaryBoolean,
+  ExtendedPagination,
+  Pagination,
+  Success,
+  UID,
+} from "../base";
+
+export class Songs extends Base {
+  /**
+   * Returns songs based on the specified filter
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param [params.filter] Filter results to match this string
+   * @param [params.exact] 0, 1 (if true filter is exact = rather than fuzzy LIKE)
+   * @param [params.add] ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date
+   * @param [params.update] ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date
+   * @param [params.offset]
+   * @param [params.limit]
+   * @param [params.cond]
+   * @param [params.sort]
+   * @see {@link https://ampache.org/api/api-json-methods#songs}
+   */
+  songs(
+    params?: {
+      filter?: string;
+      exact?: BinaryBoolean;
+      add?: Date;
+      update?: Date;
+    } & ExtendedPagination,
+  ) {
+    let query = "songs";
+    query += qs.stringify(params, "&");
+    return this.request<SongsResponse>(query);
+  }
+
+  /**
+   * Returns a single song
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param params.filter UID to find
+   * @see {@link https://ampache.org/api/api-json-methods#song}
+   */
+  song(params: { filter: UID }) {
+    let query = "song";
+    query += qs.stringify(params, "&");
+    return this.request<SongResponse>(query);
+  }
+
+  /**
+   * Songs of the specified artist
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param params.filter UID to find
+   * @param [params.top50] 0, 1 (if true filter to the artist top 50)
+   * @param [params.offset]
+   * @param [params.limit]
+   * @param [params.cond]
+   * @param [params.sort]
+   * @see {@link https://ampache.org/api/api-json-methods#artist_songs}
+   */
+  artistSongs(
+    params: {
+      filter: UID;
+      top50?: BinaryBoolean;
+    } & ExtendedPagination,
+  ) {
+    let query = "artist_songs";
+    query += qs.stringify(params, "&");
+    return this.request<SongsResponse>(query);
+  }
+
+  /**
+   * Songs of the specified album
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param params.filter UID to find
+   * @param [params.offset]
+   * @param [params.limit]
+   * @param [params.cond]
+   * @param [params.sort]
+   * @see {@link https://ampache.org/api/api-json-methods#album_songs}
+   */
+  albumSongs(
+    params: {
+      filter: UID;
+    } & ExtendedPagination,
+  ) {
+    let query = "album_songs";
+    query += qs.stringify(params, "&");
+    return this.request<SongsResponse>(query);
+  }
+
+  /**
+   * Songs of the specified genre
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param params.filter UID to find
+   * @param [params.offset]
+   * @param [params.limit]
+   * @param [params.cond]
+   * @param [params.sort]
+   * @see {@link https://ampache.org/api/api-json-methods#genre_songs}
+   */
+  genreSongs(
+    params: {
+      filter: UID;
+    } & ExtendedPagination,
+  ) {
+    let query = "genre_songs";
+    query += qs.stringify(params, "&");
+    return this.request<SongsResponse>(query);
+  }
+
+  /**
+   * This returns the songs for a playlist
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param params.filter UID to find
+   * @param [params.random] 0, 1 (if true get random songs using limit)
+   * @param [params.offset]
+   * @param [params.limit]
+   * @see {@link https://ampache.org/api/api-json-methods#playlist_songs}
+   */
+  playlistSongs(
+    params: {
+      filter: UID;
+      random?: BinaryBoolean;
+    } & Pagination,
+  ) {
+    let query = "playlist_songs";
+    query += qs.stringify(params, "&");
+    return this.request<SongsResponse>(query);
+  }
+
+  /**
+   * This returns the songs for a license
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param params.filter UID to find
+   * @param [params.offset]
+   * @param [params.limit]
+   * @param [params.cond]
+   * @param [params.sort]
+   * @see {@link https://ampache.org/api/api-json-methods#license_songs}
+   */
+  licenseSongs(
+    params: {
+      filter: UID;
+    } & ExtendedPagination,
+  ) {
+    let query = "license_songs";
+    query += qs.stringify(params, "&");
+    return this.request<SongsResponse>(query);
+  }
+
+  /**
+   * Delete an existing song. (if you are allowed to)
+   * @remarks MINIMUM_API_VERSION=5.0.0
+   * @param params.filter UID of song to delete
+   * @see {@link https://ampache.org/api/api-json-methods#song_delete}
+   */
+  songDelete(params: { filter: UID }) {
+    let query = "song_delete";
+    query += qs.stringify(params, "&");
+    return this.request<Success>(query);
+  }
+
+  /**
+   * This takes a URL and returns the song object in question
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param params.url Full Ampache URL from server
+   * @see {@link https://ampache.org/api/api-json-methods#url_to_song}
+   */
+  urlToSong(params: { url: string }) {
+    let query = "url_to_song";
+    params.url = encodeURIComponent(params.url);
+    query += qs.stringify(params, "&");
+    return this.request<SongResponse>(query);
+  }
+
+  /**
+   * This searches the songs and returns... songs
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param params.filter Filter results to match this string
+   * @param [params.offset]
+   * @param [params.limit]
+   * @see {@link https://ampache.org/api/api-json-methods#search_songs}
+   */
+  searchSongs(
+    params: {
+      filter: string;
+    } & Pagination,
+  ) {
+    let query = "search_songs";
+    query += qs.stringify(params, "&");
+    return this.request<SongsResponse>(query);
+  }
+
+  /**
+   * Returns songs that have been deleted from the server
+   * @remarks MINIMUM_API_VERSION=500000
+   * @param [params.offset]
+   * @param [params.limit]
+   * @see {@link https://ampache.org/api/api-json-methods#deleted_songs}
+   */
+  deletedSongs(params?: {} & Pagination) {
+    let query = "deleted_songs";
+    query += qs.stringify(params, "&");
+    return this.request<DeletedSongsResponse>(query);
+  }
+}

package/src/songs/types.ts

@@ -1,65 +1,77 @@
-import { ArtistSummary } from "../artists/types";
-import { GenreSummary } from "../genres/types";
-import { UID } from "../base";
-import { AlbumSummary } from "../albums/types";
-
-export type Song = {
-    id: UID,
-    title: string,
-    name: string,
-    artist: ArtistSummary,
-    album: AlbumSummary,
-    albumartist: ArtistSummary,
-    disk: number,
-    track: number
-    filename: string,
-    genre: GenreSummary[],
-    playlisttrack: number,
-    time: number,
-    year: number | string,
-    format: string,
-    stream_format: string,
-    rate: number,
-    mode: string,
-    mime: string,
-    stream_mime: string,
-    url: string,
-    size: number,
-    mbid: string | null,
-    album_mbid: string | null,
-    artist_mbid: string | null,
-    art: string,
-    has_art: boolean,
-    flag: boolean,
-    rating: number | null,
-    averagerating: number | null,
-    playcount: number,
-    catalog: number,
-    composer: string,
-    channels: number | null,
-    comment: string,
-    license: string | null,
-    publisher: string,
-    language: string,
-    lyrics: string,
-    replaygain_album_gain: number | null,
-    replaygain_album_peak: number | null,
-    replaygain_track_gain: number | null,
-    replaygain_track_peak: number | null,
-    r128_album_gain: number | null,
-    r128_track_gain: number | null,
-}
-
-export type DeletedSong = {
-    id: UID,
-    addition_time: number,
-    delete_time: number,
-    update_time: number,
-    title: string,
-    file: string,
-    catalog: UID,
-    total_count: number,
-    total_skip: number,
-    album: UID,
-    artist: UID,
-}
+import { ArtistSummary } from "../artists/types";
+import { GenreSummary } from "../genres/types";
+import { UID } from "../base";
+import { AlbumSummary } from "../albums/types";
+
+export type SongResponse = {
+  id: UID;
+  title: string;
+  name: string;
+  artist: ArtistSummary;
+  album: AlbumSummary;
+  albumartist: ArtistSummary;
+  disk: number;
+  track: number;
+  filename: string;
+  genre: GenreSummary[];
+  playlisttrack: number;
+  time: number;
+  year: number | string;
+  format: string;
+  stream_format: string;
+  rate: number;
+  mode: string;
+  mime: string;
+  stream_mime: string;
+  url: string;
+  size: number;
+  mbid: string | null;
+  album_mbid: string | null;
+  artist_mbid: string | null;
+  art: string;
+  has_art: boolean;
+  flag: boolean;
+  rating: number | null;
+  averagerating: number | null;
+  playcount: number;
+  catalog: number;
+  composer: string;
+  channels: number | null;
+  comment: string;
+  license: string | null;
+  publisher: string;
+  language: string;
+  lyrics: string;
+  replaygain_album_gain: number | null;
+  replaygain_album_peak: number | null;
+  replaygain_track_gain: number | null;
+  replaygain_track_peak: number | null;
+  r128_album_gain: number | null;
+  r128_track_gain: number | null;
+};
+
+export type SongsResponse = {
+  total_count: number;
+  md5: string;
+  song: SongResponse[];
+};
+
+export type DeletedSongResponse = {
+  id: UID;
+  addition_time: number;
+  delete_time: number;
+  update_time: number;
+  title: string;
+  file: string;
+  catalog: UID;
+  total_count: number;
+  total_skip: number;
+  album: UID;
+  artist: UID;
+};
+
+export type DeletedSongsResponse = {
+  total_count: number;
+  md5: string;
+  deleted_song: DeletedSongResponse[];
+};