javascript-ampache 0.0.1

package/src/artists/index.ts

@@ -0,0 +1,82 @@
+import qs from 'querystringify';
+import { Artist } from './types';
+import { Base, BinaryBoolean, Pagination, UID } from '../base';
+
+export class Artists extends Base {
+    /**
+     * This takes a collection of inputs and returns artist objects
+     * @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.include] (albums | songs) include child objects in the response
+     * @param [params.album_artist] 0, 1 (if true filter for album artists only)
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#artists}
+     */
+    async artists (params?: {
+        filter?: string,
+        exact?: BinaryBoolean,
+        add?: Date,
+        update?: Date,
+        include?: 'albums' | 'songs',
+        album_artist?: BinaryBoolean,
+    } & Pagination) {
+        let query = 'artists';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{artist: Artist[]}>(query);
+        return (data.artist) ? data.artist : data;
+    }
+
+    /**
+     * This returns a single artist based on the UID of said artist
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param params.filter UID to find
+     * @param [params.include] (albums | songs) include child objects in the response
+     * @see {@link https://ampache.org/api/api-json-methods#artist}
+     */
+    artist (params: {
+        filter: UID,
+        include?: 'albums' | 'songs',
+    }) {
+        let query = 'artist';
+        query += qs.stringify(params, '&');
+        return this.request<Artist>(query);
+    }
+
+    /**
+     * This returns the artists associated with the genre in question as defined by the UID
+     * @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_artists}
+     */
+    async genreArtists (params: {
+        filter: UID
+    } & Pagination) {
+        let query = 'genre_artists';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{artist: Artist[]}>(query);
+        return (data.artist) ? data.artist : data;
+    }
+
+    /**
+     * This returns the artists associated with the label in question as defined by the UID
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.filter UID of find
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#label_artists}
+     */
+    async labelArtists (params: {
+        filter: UID
+    } & Pagination) {
+        let query = 'label_artists';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{artist: Artist[]}>(query);
+        return (data.artist) ? data.artist : data;
+    }
+}

package/src/artists/types.ts

@@ -0,0 +1,31 @@
+import { Album } from "../albums/types";
+import { Song } from "../songs/types";
+import { Genre } from "../genres/types";
+
+export type ArtistSummary = {
+    id: string,
+    name: string,
+    prefix: string | null,
+    basename: string
+}
+
+export type Artist = {
+    id: string,
+    name: string,
+    prefix: string | null,
+    basename: string,
+    albums: Album[],
+    albumcount: number,
+    songs: Song[],
+    songcount: number,
+    genre: Genre[],
+    art: string,
+    flag: boolean,
+    rating: number | null,
+    averagerating: number | null,
+    mbid: string | null,
+    summary: string,
+    time: number,
+    yearformed: number,
+    placeformed: string,
+}

package/src/auth/index.ts

@@ -0,0 +1,91 @@
+import JsSHA from "jssha/dist/sha256";
+import qs from 'querystringify';
+import fetch from "isomorphic-unfetch";
+import { Base, Success } from "../base";
+import { AuthResponse } from './types'
+
+export class Auth extends Base {
+    /**
+     * Handles verifying a new handshake
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param params.auth encrypted apikey OR password if using password auth
+     * @param [params.user] username
+     * @param [params.timestamp] UNIXTIME()
+     * @param [params.version] version of Ampache API to establish connection with
+     * @see {@link https://ampache.org/api/api-json-methods#handshake}
+     */
+    handshake (params: {
+        auth: string,
+        user?: string,
+        timestamp?: number,
+        version?: string
+    }) {
+        // generate a timestamp if one wasn't provided
+        if (!params.timestamp) {
+            params.timestamp = Math.floor(new Date().getTime() / 1000);
+        }
+
+        // override the fallback API version with specified
+        if (params.version) {
+            this.version = params.version;
+        }
+
+        // drop timestamp if no user provided (i.e. logging in with API key)
+        if (!params.user) {
+            delete params.timestamp;
+        }
+
+        let query = this.url + "/server/json.server.php?action=handshake";
+        query += qs.stringify(params, '&');
+
+        return fetch(query)
+            .then(response => response.json())
+            .then(data => {
+                if (data.auth) {
+                    this.sessionKey = data.auth;
+                }
+                return <AuthResponse>data;
+            })
+    }
+
+    /**
+     * This can be called without being authenticated, it is useful for determining if what the status
+     * of the server is, and what version it is running/compatible with
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param [params.auth] (Session ID) returns version information and extends the session if passed
+     * @param [params.version] API Version that the application understands
+     * @see {@link https://ampache.org/api/api-json-methods#ping}
+     */
+    ping (params?: { auth?: string, version?: string }) {
+        let query = 'ping';
+        query += qs.stringify(params, '&');
+        return this.request<AuthResponse>(query, false);
+    }
+
+    /**
+     * Destroy a session using the session auth parameter
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.auth Session ID to destroy
+     * @see {@link https://ampache.org/api/api-json-methods#goodbye}
+     */
+    goodbye (params: { auth }) {
+        let query = 'goodbye';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query, false);
+    }
+
+    /**
+     * Encrypt your password into the accepted format.
+     */
+    encryptPassword (params: { password: string, time: number }) {
+        let key = getSHA256(params.password);
+        return getSHA256(params.time + key);
+
+        function getSHA256(text) {
+            let shaObj = new JsSHA("SHA-256", "TEXT", { encoding: "UTF8" });
+            shaObj.update(text);
+
+            return shaObj.getHash("HEX");
+        }
+    }
+}

package/src/auth/types.ts

@@ -0,0 +1,22 @@
+export type AuthResponse = {
+    auth: string,
+    api: string,
+    session_expire: string,
+    update: string,
+    add: string,
+    clean: string,
+    songs: number,
+    albums: number,
+    artists: number,
+    genres: number,
+    playlists: number,
+    user: number,
+    catalogs: number,
+    videos: number,
+    podcasts: number,
+    podcast_episodes: number,
+    shares: number,
+    licenses: number,
+    live_streams: number,
+    labels: number,
+}

package/src/base.ts

@@ -0,0 +1,64 @@
+import fetch from 'isomorphic-unfetch';
+
+type Config = {
+    url: string,
+    sessionKey?: string,
+    debug?: boolean,
+}
+
+export type Success = {
+    success: string,
+}
+
+/**
+ * @param [offset] Return results starting from this index position
+ * @param [limit] Maximum number of results to return
+ */
+export type Pagination = {
+    offset?: number,
+    limit?: number,
+}
+
+export type BinaryBoolean = 0 | 1;
+
+export type UID = string | number;
+
+export abstract class Base {
+    sessionKey: string;
+    url: string;
+    version: string = '6.0.0';// default to latest version
+    debug: boolean;
+
+    constructor(config: Config) {
+        this.sessionKey = config.sessionKey || null;
+        this.url = config.url;
+        this.debug = config.debug || false;
+    }
+
+    protected request<T> (endpoint: string, includeAuth: boolean = true): Promise<T> {
+        let url = this.url + "/server/json.server.php?action=" + endpoint;
+
+        // some endpoints like ping() or goodbye() can pass their own auth
+        if (includeAuth) {
+            url += "&auth=" + this.sessionKey + "&version=" + this.version;
+        }
+
+        if (this.debug) {
+            console.debug(
+                "javascript-ampache query URL %c" + url,
+                "color: black; font-style: italic; background-color: orange;padding: 2px"
+            );
+        }
+
+        return fetch(url).then(r => {
+            if (r.ok) {
+                return r.json();
+            }
+            throw new Error(r.statusText);
+        })
+    }
+
+    public setSessionKey(sessionKey: string) {
+        this.sessionKey = sessionKey;
+    }
+}

package/src/bookmarks/index.ts

@@ -0,0 +1,94 @@
+import qs from 'querystringify';
+import { Bookmark } from './types';
+import { Base, Success, UID } from '../base';
+
+export class Bookmarks extends Base {
+    /**
+     * Get information about bookmarked media this user is allowed to manage
+     * @remarks MINIMUM_API_VERSION=5.0.0
+     * @see {@link https://ampache.org/api/api-json-methods#bookmarks}
+     */
+    async bookmarks () {
+        let query = 'bookmarks';
+        let data = await this.request<{bookmark: Bookmark[]}>(query);
+        return (data.bookmark) ? data.bookmark : data;
+    }
+
+    /**
+     * Get the bookmark from it's object_id and object_type.
+     * @remarks MINIMUM_API_VERSION=5.0.0
+     * @param params.filter UID to find
+     * @param params.type Object type
+     * @see {@link https://ampache.org/api/api-json-methods#get_bookmark}
+     */
+    getBookmark (params: {
+        filter: UID,
+        type: 'song' | 'video' | 'podcast_episode',
+    }) {
+        let query = 'get_bookmark';
+        query += qs.stringify(params, '&');
+        return this.request<Bookmark>(query);
+    }
+
+    /**
+     * Create a placeholder for the current media that you can return to later.
+     * @remarks MINIMUM_API_VERSION=5.0.0
+     * @param params.filter UID to find
+     * @param params.type Object type
+     * @param params.position current track time in seconds
+     * @param [params.client] Agent string. (Default: 'AmpacheAPI')
+     * @param [params.date] update time (Default: UNIXTIME())
+     * @see {@link https://ampache.org/api/api-json-methods#bookmark_create}
+     */
+    bookmarkCreate (params: {
+        filter: UID,
+        type: 'song' | 'video' | 'podcast_episode',
+        position: number,
+        client?: string,
+        date?: number,
+    }) {
+        let query = 'bookmark_create';
+        query += qs.stringify(params, '&');
+        return this.request<Bookmark>(query);
+    }
+
+    /**
+     * Edit a placeholder for the current media that you can return to later.
+     * @remarks MINIMUM_API_VERSION=5.0.0
+     * @param params.filter UID to find
+     * @param params.type Object type
+     * @param params.position current track time in seconds
+     * @param [params.client] Agent string. (Default: 'AmpacheAPI')
+     * @param [params.date] update time (Default: UNIXTIME())
+     * @see {@link https://ampache.org/api/api-json-methods#bookmark_edit}
+     */
+    bookmarkEdit (params: {
+        filter: UID,
+        type: 'song' | 'video' | 'podcast_episode',
+        position: number,
+        client?: string,
+        date?: number,
+    }) {
+        let query = 'bookmark_edit';
+        query += qs.stringify(params, '&');
+        return this.request<Bookmark>(query);
+    }
+
+    /**
+     * Delete an existing bookmark. (if it exists)
+     * @remarks MINIMUM_API_VERSION=5.0.0
+     * @param params.filter UID to find
+     * @param params.type Object type
+     * @param [params.client] Agent string. (Default: 'AmpacheAPI')
+     @see {@link https://ampache.org/api/api-json-methods#bookmark_delete}
+     */
+    bookmarkDelete (params: {
+        filter: UID,
+        type: 'song' | 'video' | 'podcast_episode',
+        client?: string,
+    }) {
+        let query = 'bookmark_delete';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+}

package/src/bookmarks/types.ts

@@ -0,0 +1,9 @@
+import { UID } from "../base";
+
+export type Bookmark = {
+    id: UID,
+    type: 'song' | 'video' | 'podcast_episode',
+    position: number,
+    client?: string,
+    date?: number,
+}

package/src/catalogs/index.ts

@@ -0,0 +1,71 @@
+import qs from 'querystringify';
+import { Catalog } from './types';
+import { Base, Success, UID } from '../base';
+
+export class Catalogs extends Base {
+    /**
+     * This searches the catalogs and returns... catalogs
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param [params.filter] Catalog type
+     * @see {@link https://ampache.org/api/api-json-methods#catalogs}
+     */
+    async catalogs (params?: {
+        filter?: 'music' | 'clip' | 'tvshow' | 'movie' | 'personal_video' | 'podcast',
+    }) {
+        let query = 'catalogs';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{catalog: Catalog[]}>(query);
+        return (data.catalog) ? data.catalog : data;
+    }
+
+    /**
+     * Return catalog by UID
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.filter UID to find
+     * @see {@link https://ampache.org/api/api-json-methods#catalog}
+     */
+    catalog (params: {
+        filter: UID,
+    }) {
+        let query = 'catalog';
+        query += qs.stringify(params, '&');
+        return this.request<Catalog>(query);
+    }
+
+    /**
+     * Kick off a catalog update or clean for the selected catalog
+     * ACCESS REQUIRED: 75 (Catalog Manager)
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.task add_to_catalog, clean_catalog
+     * @param params.catalog UID of catalog
+     * @see {@link https://ampache.org/api/api-json-methods#catalog_action}
+     */
+    catalogAction(params: {
+        task: 'add_to_catalog' | 'clean_catalog',
+        catalog: UID,
+    }) {
+        let query = 'catalog_action';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+
+    /**
+     * Perform actions on local catalog files. Single file versions of catalog add, clean, verify and remove (delete).
+     * Make sure you remember to urlencode those file names!
+     * ACCESS REQUIRED: 50 (Content Manager)
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.file FULL path to local file
+     * @param params.task add, clean, verify, remove, (can include comma-separated values)
+     * @param params.catalog UID of catalog
+     * @see {@link https://ampache.org/api/api-json-methods#catalog_file}
+     */
+    catalogFile(params: {
+        file: string,
+        task: string,
+        catalog: UID,
+    }) {
+        let query = 'catalog_file';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+}

package/src/catalogs/types.ts

@@ -0,0 +1,15 @@
+import { UID } from "../base";
+
+export type Catalog = {
+    id: UID,
+    name: string,
+    type: 'local' | 'remote',
+    gather_types: 'podcast' | 'clip' | 'tvshow' | 'movie' | 'personal_video' | 'music',
+    enabled: boolean,
+    last_add: number,
+    last_clean: number,
+    last_update: number,
+    path: string,
+    rename_pattern: string,
+    sort_pattern: string,
+}

package/src/genres/index.ts

@@ -0,0 +1,39 @@
+import qs from 'querystringify';
+import { Genre } from './types';
+import { Base, BinaryBoolean, Pagination, UID } from '../base';
+
+export class Genres extends Base {
+    /**
+     * This returns the genres (Tags) based on the specified filter
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param [params.filter] UID to find
+     * @param [params.exact] 0, 1 (if true filter is exact = rather than fuzzy LIKE)
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#genres}
+     */
+    async genres (params?: {
+        filter?: string,
+        exact?: BinaryBoolean,
+    } & Pagination) {
+        let query = 'genres';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{genre: Genre[]}>(query);
+        return (data.genre) ? data.genre : data;
+    }
+
+    /**
+     * This returns a single genre based on UID
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param params.filter UID to find
+     * @see {@link https://ampache.org/api/api-json-methods#genre}
+     */
+    async genre (params: {
+        filter: UID,
+    }) {
+        let query = 'genre';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{genre: Genre[]}>(query);
+        return (data.genre) ? data.genre : data;
+    }
+}

package/src/genres/types.ts

@@ -0,0 +1,17 @@
+import { UID } from "../base";
+
+export type GenreSummary = {
+    id: UID,
+    name: string,
+}
+
+export type Genre = {
+    id: UID,
+    name: string,
+    albums: number,
+    artists: number,
+    songs: number,
+    videos: number,
+    playlists: number,
+    live_streams: number,
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+import { Albums } from './albums';
+import { Artists } from './artists';
+import { Auth } from './auth';
+import { Bookmarks } from './bookmarks';
+import { Catalogs } from './catalogs';
+import { Genres } from './genres';
+import { Labels } from './labels';
+import { Licenses } from './licenses';
+import { LiveStreams } from './live-streams';
+import { Playlists } from './playlists';
+import { Podcasts } from './podcasts';
+import { Preferences } from './preferences';
+import { Shares } from './shares';
+import { Shouts } from './shouts';
+import { Songs } from './songs';
+import { System } from './system';
+import { Users } from './users';
+import { Videos } from './videos';
+import { applyMixins } from './utils';
+import { Base } from './base';
+
+class AmpacheAPI extends Base {}
+interface AmpacheAPI extends Albums, Artists, Auth, Bookmarks, Catalogs, Genres, Labels, Licenses, LiveStreams, Playlists, Podcasts, Preferences, Shares, Shouts, Songs, System, Users, Videos {}
+applyMixins(AmpacheAPI, [Albums, Artists, Auth, Bookmarks, Catalogs, Genres, Labels, Licenses, LiveStreams, Playlists, Podcasts, Preferences, Shares, Shouts, Songs, System, Users, Videos]);
+
+export default AmpacheAPI

package/src/labels/index.ts

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

package/src/labels/types.ts

@@ -0,0 +1,14 @@
+import { UID } from "../base";
+
+export type Label = {
+    id: UID,
+    name: string,
+    artists: number,
+    summary: string | null,
+    external_link: string | null,
+    address: string | null,
+    category: string | null,
+    email: string | null,
+    website: string | null,
+    user: UID,
+}

package/src/licenses/index.ts

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

package/src/licenses/types.ts

@@ -0,0 +1,8 @@
+import { UID } from "../base";
+
+export type License = {
+    id: UID,
+    name: string,
+    description: string,
+    external_link: string,
+}