javascript-ampache 0.0.1

package/src/shares/index.ts

@@ -0,0 +1,94 @@
+import qs from 'querystringify';
+import { Share } from './types';
+import { Base, BinaryBoolean, Pagination, Success, UID } from '../base';
+
+export class Shares extends Base {
+    /**
+     * This searches the shares and returns... shares
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param [params.filter] UID to find
+     * @param [params.exact] 0, 1 boolean to match the exact filter string
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#shares}
+     */
+    async shares (params?: {
+        filter?: string,
+        exact?: BinaryBoolean,
+    } & Pagination) {
+        let query = 'shares';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{share: Share[]}>(query);
+        return (data.share) ? data.share : data;
+    }
+
+    /**
+     * Return a share from UID
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.filter UID to find
+     * @see {@link https://ampache.org/api/api-json-methods#share}
+     */
+    share (params: {
+        filter: UID,
+    }) {
+        let query = 'share';
+        query += qs.stringify(params, '&');
+        return this.request<Share>(query);
+    }
+
+    /**
+     * Create a public url that can be used by anyone to stream media.
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.filter UID of object you are sharing
+     * @param params.type ('song', 'album', 'artist')
+     * @param [params.description] description (will be filled for you if empty)
+     * @param [params.expires] days to keep active
+     * @see {@link https://ampache.org/api/api-json-methods#share_create}
+     */
+    shareCreate (params: {
+        filter: UID,
+        type: 'song' | 'album' | 'artist',
+        description?: string,
+        expires?: number,
+    }) {
+        let query = 'share_create';
+        query += qs.stringify(params, '&');
+        return this.request<Share>(query);
+    }
+
+    /**
+     * Update the description and/or expiration date for an existing share
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.filter UID to find
+     * @param [params.stream] 0, 1
+     * @param [params.download] 0, 1
+     * @param [params.expires] days to keep active
+     * @param [params.description] description
+     * @see {@link https://ampache.org/api/api-json-methods#share_edit}
+     */
+    shareEdit (params: {
+        filter: UID,
+        stream?: BinaryBoolean,
+        download?: BinaryBoolean,
+        expires?: number,
+        description?: string,
+    }) {
+        let query = 'share_edit';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+
+    /**
+     * Delete an existing share.
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.filter UID of share to delete
+     * @see {@link https://ampache.org/api/api-json-methods#share_delete}
+     */
+    shareDelete (params: {
+        filter: UID,
+    }) {
+        let query = 'share_delete';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+}

package/src/shares/types.ts

@@ -0,0 +1,19 @@
+import { UID } from "../base";
+
+export type Share = {
+    id: UID,
+    name: string,
+    owner: string,
+    allow_stream: boolean,
+    allow_download: boolean,
+    creation_date: number,
+    lastvisit_date: number,
+    object_type: string,
+    object_id: UID,
+    expire_days: number,
+    max_counter: number,
+    counter: number,
+    secret: string,
+    public_url: string,
+    description: string,
+}

package/src/shouts/index.ts

@@ -0,0 +1,22 @@
+import qs from 'querystringify';
+import { Shout } from './types';
+import { Base } from '../base';
+
+export class Shouts extends Base {
+    /**
+     * This gets the latest posted shouts
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param [params.username] Username to find
+     * @param [params.limit] Maximum number of results to return
+     * @see {@link https://ampache.org/api/api-json-methods#last_shouts}
+     */
+    async last_shouts (params?: {
+        username?: string,
+        limit?: number
+    }) {
+        let query = 'last_shouts';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{shout: Shout[]}>(query);
+        return (data.shout) ? data.shout : data;
+    }
+}

package/src/shouts/types.ts

@@ -0,0 +1,9 @@
+import { UID } from "../base";
+import { UserSummary } from "../users/types";
+
+export type Shout = {
+    id: UID,
+    date: number,
+    text: string,
+    user: UserSummary,
+}

package/src/songs/index.ts

@@ -0,0 +1,191 @@
+import qs from 'querystringify';
+import { Song, DeletedSong } from './types';
+import { Base, BinaryBoolean, 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]
+     * @see {@link https://ampache.org/api/api-json-methods#songs}
+     */
+    async songs (params?: {
+        filter?: string,
+        exact?: BinaryBoolean,
+        add?: Date,
+        update?: Date,
+    } & Pagination) {
+        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]
+     * @see {@link https://ampache.org/api/api-json-methods#artist_songs}
+     */
+    async artistSongs (params: {
+        filter: UID,
+        top50?: BinaryBoolean,
+    } & Pagination) {
+        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]
+     * @see {@link https://ampache.org/api/api-json-methods#album_songs}
+     */
+    async albumSongs (params: {
+        filter: UID,
+    } & Pagination) {
+        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]
+     * @see {@link https://ampache.org/api/api-json-methods#genre_songs}
+     */
+    async genreSongs (params: {
+        filter: UID,
+    } & Pagination) {
+        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.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#playlist_songs}
+     */
+    async playlistSongs (params: {
+        filter: UID,
+    } & 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]
+     * @see {@link https://ampache.org/api/api-json-methods#license_songs}
+     */
+    async licenseSongs (params: {
+        filter: UID,
+    } & Pagination) {
+        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;
+    }
+}

package/src/songs/types.ts

@@ -0,0 +1,64 @@
+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,
+    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,
+}