javascript-ampache 0.0.1

package/src/live-streams/index.ts

@@ -0,0 +1,42 @@
+import qs from 'querystringify';
+import { LiveStream } from './types';
+import { Base, BinaryBoolean, Pagination, UID } from '../base';
+
+export class LiveStreams extends Base {
+    /**
+     * This returns live_streams based on the specified filter
+     * @remarks MINIMUM_API_VERSION=5.1.0
+     * @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]
+     * @see {@link https://ampache.org/api/api-json-methods#live_streams}
+     */
+    async liveStreams (params?: {
+        filter?: string,
+        exact?: BinaryBoolean,
+        add?: Date,
+        update?: Date,
+    } & Pagination) {
+        let query = 'live_streams';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{live_stream: LiveStream[]}>(query);
+        return (data.live_stream) ? data.live_stream : data;
+    }
+
+    /**
+     * This returns a single live_stream
+     * @remarks MINIMUM_API_VERSION=5.1.0
+     * @param params.filter UID to find
+     * @see {@link https://ampache.org/api/api-json-methods#live_stream}
+     */
+    liveStream (params: {
+        filter: UID,
+    }) {
+        let query = 'live_stream';
+        query += qs.stringify(params, '&');
+        return this.request<LiveStream>(query);
+    }
+}

package/src/live-streams/types.ts

@@ -0,0 +1,10 @@
+import { UID } from "../base";
+
+export type LiveStream = {
+    id: UID,
+    name: string,
+    url: string,
+    codec: string,
+    catalog: UID,
+    site_url: string,
+}

package/src/playlists/index.ts

@@ -0,0 +1,198 @@
+import qs from 'querystringify';
+import { Playlist } from './types';
+import { Song } from "../songs/types";
+import { Base, BinaryBoolean, Pagination, Success, UID } from '../base';
+
+export class Playlists extends Base {
+    /**
+     * This returns playlists 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.hide_search] 0, 1 (if true do not include searches/smartlists in the result)
+     * @param [params.show_dupes] 0, 1 (if true ignore 'api_hide_dupe_searches' setting)
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#playlists}
+     */
+    async playlists (params?: {
+        filter?: string,
+        exact?: BinaryBoolean,
+        add?: Date,
+        update?: Date,
+        hide_search?: BinaryBoolean,
+        show_dupes?: BinaryBoolean,
+    } & Pagination) {
+        let query = 'playlists';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{playlist: Playlist[]}>(query);
+        return (data.playlist) ? data.playlist : data;
+    }
+
+    /**
+     * This returns smartlists based on the specified filter. NOTE: Filtered from Playlists() so pagination is invalid.
+     * @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.show_dupes] 0, 1 (if true ignore 'api_hide_dupe_searches' setting)
+     * @see {@link https://ampache.org/api/api-json-methods#playlists}
+     */
+    async smartlists (params?: {
+        filter?: string,
+        exact?: BinaryBoolean,
+        add?: Date,
+        update?: Date,
+        show_dupes?: BinaryBoolean,
+    }) {
+        let query = 'playlists';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{playlist: Playlist[]}>(query);
+
+        let results = (data.playlist) ? data.playlist : data;
+
+        // filter out regular playlists
+        if (Array.isArray(results)) {
+            results = results.filter(function(item) {
+                return item.id.toString().match(/^smart_/);
+            })
+        }
+
+        return results;
+    }
+
+    /**
+     * This returns a single playlist
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param params.filter UID to find
+     * @see {@link https://ampache.org/api/api-json-methods#playlist}
+     */
+    playlist (params: {
+        filter: UID
+    }) {
+        let query = 'playlist';
+        query += qs.stringify(params, '&');
+        return this.request<Playlist>(query);
+    }
+
+    /**
+     * This creates a new playlist and returns it
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param params.name Playlist name
+     * @param [params.type] public, private (Playlist type)
+     * @see {@link https://ampache.org/api/api-json-methods#playlist_create}
+     */
+    playlistCreate (params: {
+        name: string,
+        type?: 'public' | 'private',
+    }) {
+        let query = 'playlist_create';
+        query += qs.stringify(params, '&');
+        return this.request<Playlist>(query);
+    }
+
+    /**
+     * This modifies name and type of a playlist.
+     * NOTE items and tracks must be sent together and be of equal length.
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.filter UID to find
+     * @param [params.name] Playlist name
+     * @param [params.type] public, private (Playlist type)
+     * @param [params.owner] Change playlist owner to the user id (-1 = System playlist)
+     * @param [params.items] comma-separated song_id's (replaces existing items with a new id)
+     * @param [params.tracks] comma-separated playlisttrack numbers matched to 'items' in order
+     * @see {@link https://ampache.org/api/api-json-methods#playlist_edit}
+     */
+    playlistEdit (params: {
+        filter: UID,
+        name?: string,
+        type?: 'public' | 'private',
+        owner?: string,
+        items?: string,
+        tracks?: string,
+    }) {
+        let query = 'playlist_edit';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+
+    /**
+     * This deletes a playlist
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param params.filter UID of playlist to delete
+     * @see {@link https://ampache.org/api/api-json-methods#playlist_delete}
+     */
+    playlistDelete (params: {
+        filter: UID,
+    }) {
+        let query = 'playlist_delete';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+
+    /**
+     * This adds a song to a playlist
+     * @remarks MINIMUM_API_VERSION=380001; CHANGED_IN_API_VERSION=400003
+     * @param params.filter UID of Playlist
+     * @param params.song UID of song to add to playlist
+     * @param [params.check] 0, 1 Whether to check and ignore duplicates (default = 0)
+     * @see {@link https://ampache.org/api/api-json-methods#playlist_add_song}
+     */
+    playlistAddSong (params: {
+        filter: UID,
+        song: UID,
+        check?: BinaryBoolean,
+    }) {
+        let query = 'playlist_add_song';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+
+    /**
+     * This remove a song from a playlist
+     * @remarks MINIMUM_API_VERSION=380001; CHANGED_IN_API_VERSION=400001
+     * @param params.filter UID of Playlist
+     * @param [params.song] UID of song to remove from playlist
+     * @param [params.track] Track number to remove from playlist
+     * @see {@link https://ampache.org/api/api-json-methods#playlist_remove_song}
+     */
+    playlistRemoveSong (params: {
+        filter: UID,
+        song?: UID,
+        track?: number,
+    }) {
+        let query = 'playlist_remove_song';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+
+    /**
+     * Get a list of song JSON, indexes or id's based on some simple search criteria
+     * @remarks MINIMUM_API_VERSION=400001; CHANGED_IN_API_VERSION=400002; 'recent' will search for tracks played after 'Popular Threshold' days; 'forgotten' will search for tracks played before 'Popular Threshold' days; 'unplayed' added in 400002 for searching unplayed tracks
+     * @param [params.mode] (default = 'random')
+     * @param [params.filter] string LIKE matched to song title
+     * @param [params.album] UID of album
+     * @param [params.artist] UID of artist
+     * @param [params.flag] 0, 1 (get flagged songs only. default = 0)
+     * @param [params.format] song, index, id (default = 'song')
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#playlist_generate}
+     */
+    async playlistGenerate (params?: {
+        mode?: 'recent' | 'forgotten' | 'unplayed' | 'random',
+        filter?: string,
+        album?: number,
+        artist?: number,
+        flag?: BinaryBoolean,
+        format?: 'song' | 'index' | 'id',
+    } & Pagination) {
+        let query = 'playlist_generate';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{song: Song[]}>(query);
+        return (data.song) ? data.song : data;
+    }
+}

package/src/playlists/types.ts

@@ -0,0 +1,13 @@
+import { UID } from "../base";
+
+export type Playlist = {
+    id: UID,
+    name: string,
+    owner: string,
+    items: number,
+    type: 'public' | 'private',
+    art: string,
+    flag: boolean,
+    rating: number | null,
+    averagerating: number | null,
+}

package/src/podcasts/index.ts

@@ -0,0 +1,174 @@
+import qs from 'querystringify';
+import { Podcast, PodcastEpisode, DeletedPodcastEpisode } from './types';
+import { Base, Pagination, Success, UID } from '../base';
+
+export class Podcasts extends Base {
+    /**
+     * Get information about podcasts
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param [params.filter] Value is Alpha Match for returned results, may be more than one letter/number
+     * @param [params.include] episodes (include podcast_episodes in the response)
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#podcasts}
+     */
+    async podcasts (params?: {
+        filter?: string,
+        include?: 'episodes',
+    } & Pagination) {
+        let query = 'podcasts';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{podcast: Podcast[]}>(query);
+        return (data.podcast) ? data.podcast : data;
+    }
+
+    /**
+     * Get information about podcasts
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.filter UID to find
+     * @param [params.include] episodes (include podcast_episodes in the response)
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#podcast}
+     */
+    async podcast (params?: {
+        filter: UID,
+        include?: 'episodes',
+    } & Pagination) {
+        let query = 'podcast';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{podcast: Podcast[]}>(query);
+        return (data.podcast) ? data.podcast : data;
+    }
+
+    /**
+     * Create a podcast that can be used by anyone to stream media.
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.url RSS url for podcast
+     * @param params.catalog UID of podcast catalog
+     * @see {@link https://ampache.org/api/api-json-methods#podcast_create}
+     */
+    podcastCreate (params: {
+        url: string,
+        catalog: UID,
+    }) {
+        let query = 'podcast_create';
+        query += qs.stringify(params, '&');
+        return this.request<Podcast>(query);
+    }
+
+    /**
+     * Update the description and/or expiration date for an existing podcast.
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.filter UID to find
+     * @param [params.feed] RSS url for podcast
+     * @param [params.title] Podcast title
+     * @param [params.website] Source website URL
+     * @param [params.description] Podcast description
+     * @param [params.generator] Podcast generator
+     * @param [params.copyright] Podcast copyright
+     * @see {@link https://ampache.org/api/api-json-methods#podcast_edit}
+     */
+    podcastEdit (params: {
+        filter: UID,
+        feed?: string,
+        title?: string,
+        website?: string,
+        description?: string,
+        generator?: string,
+        copyright?: string,
+    }) {
+        let query = 'podcast_edit';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+
+    /**
+     * Delete an existing podcast
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.filter UID of podcast to delete
+     * @see {@link https://ampache.org/api/api-json-methods#podcast_delete}
+     */
+    podcastDelete (params: {
+        filter: UID
+    }) {
+        let query = 'podcast_delete';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+
+    /**
+     * This returns the episodes for a podcast
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.filter UID of podcast
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#podcast_episodes}
+     */
+    async podcastEpisodes (params: {
+        filter: UID,
+    } & Pagination) {
+        let query = 'podcast_episodes';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{podcast_episode: PodcastEpisode[]}>(query);
+        return (data.podcast_episode) ? data.podcast_episode : data;
+    }
+
+    /**
+     * Get the podcast_episode from a UID
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.filter UID of podcast
+     * @see {@link https://ampache.org/api/api-json-methods#podcast_episode}
+     */
+    podcastEpisode (params: {
+        filter: UID,
+    }) {
+        let query = 'podcast_episode';
+        query += qs.stringify(params, '&');
+        return this.request<PodcastEpisode>(query);
+    }
+
+    /**
+     * Delete an existing podcast_episode
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.filter UID of podcast episode to delete
+     * @see {@link https://ampache.org/api/api-json-methods#podcast_episode_delete}
+     */
+    podcastEpisodeDelete (params: {
+        filter: UID,
+    }) {
+        let query = 'podcast_episode_delete';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+
+    /**
+     * Sync and download new podcast episodes
+     * ACCESS REQUIRED: 50 (Content Manager)
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.id UID of podcast
+     * @see {@link https://ampache.org/api/api-json-methods#update_podcast}
+     */
+    updatePodcast (params: {
+        id: UID,
+    }) {
+        let query = 'update_podcast';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+
+    /**
+     * This returns the episodes for a podcast that have been deleted
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#deleted_podcast_episodes}
+     */
+    async deletedPodcastEpisodes (params?: {
+
+    } & Pagination) {
+        let query = 'deleted_podcast_episodes';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{deleted_podcast_episode: DeletedPodcastEpisode[]}>(query);
+        return (data.deleted_podcast_episode) ? data.deleted_podcast_episode : data;
+    }
+}

package/src/podcasts/types.ts

@@ -0,0 +1,60 @@
+import { UID } from "../base";
+
+export type Podcast = {
+    id: UID,
+    name: string,
+    description: string,
+    language: string,
+    copyright: string,
+    feed_url: string,
+    generator: string,
+    website: string,
+    build_date: string,
+    sync_date: string,
+    public_url: string,
+    art: string,
+    flag: boolean,
+    rating: number | null,
+    averaterating: number | null,
+    podcast_episode: PodcastEpisode[]
+}
+
+export type PodcastEpisode = {
+    id: UID,
+    title: string,
+    name: string,
+    description: string,
+    category: string,
+    author: string,
+    author_full: string,
+    website: string,
+    pubdate: string,
+    state: 'completed' | 'pending'
+    filelength: string,
+    filesize: string,
+    filename: string,
+    mime: string,
+    time: number,
+    size: number,
+    public_url: string,
+    url: string,
+    catalog: UID,
+    art: string,
+    flag: boolean,
+    rating: number | null,
+    averagerating: number | null,
+    playcount: number,
+    played: string,
+}
+
+export type DeletedPodcastEpisode = {
+    id: UID,
+    addition_time: number,
+    delete_time: number,
+    title: string,
+    file: string,
+    catalog: UID,
+    total_count: number,
+    total_skip: number,
+    podcast: UID,
+}

package/src/preferences/index.ts

@@ -0,0 +1,118 @@
+import qs from 'querystringify';
+import { Base, BinaryBoolean, Success } from '../base';
+import { Preference } from "./types";
+
+export class Preferences extends Base {
+    /**
+     * Get your server preferences
+     * ACCESS REQUIRED: 100 (Admin)
+     * @remarks MINIMUM_API_VERSION=5.0.0
+     * @see {@link https://ampache.org/api/api-json-methods#system_preferences}
+     */
+    async systemPreferences () {
+        let query = 'system_preferences';
+        let data = await this.request<{preference: Preference[]}>(query);
+        return (data.preference) ? data.preference : data;
+    }
+
+    /**
+     * Get your system preference by name
+     * ACCESS REQUIRED: 100 (Admin)
+     * @remarks MINIMUM_API_VERSION=5.0.0
+     * @param params.systemPreference Preference name e.g ('notify_email', 'ajax_load')
+     * @see {@link https://ampache.org/api/api-json-methods#system_preference}
+     */
+    async systemPreference (params: {
+        filter: string,
+    }) {
+        let query = 'system_preference';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{Preference}>(query);
+        return data[0];
+    }
+
+    /**
+     * Get your user preferences
+     * @remarks MINIMUM_API_VERSION=5.0.0
+     * @see {@link https://ampache.org/api/api-json-methods#user_preferences}
+     */
+    async userPreferences () {
+        let query = 'user_preferences';
+        let data = await this.request<{preference: Preference[]}>(query);
+        return (data.preference) ? data.preference : data;
+    }
+
+    /**
+     * Get your user preference by name
+     * @remarks MINIMUM_API_VERSION=5.0.0
+     * @param params.filter Preference name e.g ('notify_email', 'ajax_load')
+     * @see {@link https://ampache.org/api/api-json-methods#user_preference}
+     */
+    async userPreference (params: {
+        filter: string,
+    }) {
+        let query = 'user_preference';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{Preference}>(query);
+        return data[0];
+    }
+
+    /**
+     * Add a new preference to your server
+     * ACCESS REQUIRED: 100 (Admin)
+     * @param params.filter Preference name e.g ('notify_email', 'ajax_load')
+     * @param params.type boolean, integer, string, special
+     * @param params.default string or integer default value
+     * @param params.category Category type
+     * @param [params.description]
+     * @param [params.subcategory]
+     * @param [params.level] access level required to change the value (default 100)
+     * @see {@link https://ampache.org/api/api-json-methods#preference_create}
+     */
+    preferenceCreate(params: {
+        filter: string,
+        type: 'boolean' | 'integer' | 'string' | 'special',
+        default: string | number,
+        category: 'interface' | 'internal' | 'options' | 'playlist' | 'plugins' | 'streaming' | 'system',
+        description?: string,
+        subcategory?: string,
+        level?: number,
+    }) {
+        let query = 'preference_create';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+
+    /**
+     * Edit a preference value and apply to all users if allowed
+     * ACCESS REQUIRED: 100 (Admin)
+     * @remarks MINIMUM_API_VERSION=5.0.0
+     * @param params.filter Preference name e.g ('notify_email', 'ajax_load')
+     * @param params.value (string/integer) Preference value
+     * @param [params.all] 0, 1 apply to all users
+     * @see {@link https://ampache.org/api/api-json-methods#preference_edit}
+     */
+    preferenceEdit(params: {
+        filter: string,
+        value: string | number,
+        all?: BinaryBoolean,
+    }) {
+        let query = 'preference_edit';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+
+    /**
+     * Delete a non-system preference by name
+     * ACCESS REQUIRED: 100 (Admin)
+     * @param params.filter Preference name e.g ('notify_email', 'ajax_load')
+     * @see {@link https://ampache.org/api/api-json-methods#preference_delete}
+     */
+    preferenceDelete(params: {
+        filter: string,
+    }) {
+        let query = 'preference_delete';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+}

package/src/preferences/types.ts

@@ -0,0 +1,12 @@
+import { UID } from "../base";
+
+export type Preference = {
+    id: UID,
+    name: string,
+    level: string,
+    description: string,
+    value: string,
+    type: string,
+    category: string,
+    subcategory: string | null
+}