javascript-ampache 1.0.5 → 1.0.7

package/dist/playlists/index.d.ts

@@ -53,6 +53,44 @@ export declare class Playlists extends Base {
     playlist(params: {
         filter: UID;
     }): Promise<Playlist>;
+    /**
+     * This returns a user's playlists based on the specified filter
+     * @remarks MINIMUM_API_VERSION=6.3.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#user_playlists}
+     */
+    userPlaylists(params?: {
+        filter?: string;
+        exact?: BinaryBoolean;
+        add?: Date;
+        update?: Date;
+    } & Pagination): Promise<Playlist[] | {
+        playlist: Playlist[];
+    }>;
+    /**
+     * This returns a user's smartlists based on the specified filter
+     * @remarks MINIMUM_API_VERSION=6.3.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#user_smartlists}
+     */
+    userSmartlists(params?: {
+        filter?: string;
+        exact?: BinaryBoolean;
+        add?: Date;
+        update?: Date;
+    } & Pagination): Promise<Playlist[] | {
+        playlist: Playlist[];
+    }>;
     /**
      * This creates a new playlist and returns it
      * @remarks MINIMUM_API_VERSION=380001
@@ -64,6 +102,19 @@ export declare class Playlists extends Base {
         name: string;
         type?: 'public' | 'private';
     }): Promise<Playlist>;
+    /**
+     * This adds an item to a playlist
+     * @remarks MINIMUM_API_VERSION=6.3.0
+     * @param params.filter UID of Playlist
+     * @param params.id UID of the object to add to playlist
+     * @param params.type 'song', 'album', 'artist', 'playlist'
+     * @see {@link https://ampache.org/api/api-json-methods#playlist_add}
+     */
+    playlistAdd(params: {
+        filter: UID;
+        id: UID;
+        type: 'song' | 'album' | 'artist' | 'playlist';
+    }): Promise<Success>;
     /**
      * This modifies name and type of a playlist.
      * NOTE items and tracks must be sent together and be of equal length.
@@ -100,6 +151,7 @@ export declare class Playlists extends Base {
      * @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}
+     * @deprecated Being removed in 7.0.0. Use `playlist_add` instead.
      */
     playlistAddSong(params: {
         filter: UID;

package/dist/playlists/types.d.ts

@@ -6,6 +6,7 @@ export type Playlist = {
     items: number;
     type: 'public' | 'private';
     art: string;
+    has_art: boolean;
     flag: boolean;
     rating: number | null;
     averagerating: number | null;

package/dist/podcasts/types.d.ts

@@ -12,6 +12,7 @@ export type Podcast = {
     sync_date: string;
     public_url: string;
     art: string;
+    has_art: boolean;
     flag: boolean;
     rating: number | null;
     averaterating: number | null;
@@ -43,6 +44,7 @@ export type PodcastEpisode = {
     url: string;
     catalog: UID;
     art: string;
+    has_art: boolean;
     flag: boolean;
     rating: number | null;
     averagerating: number | null;

package/dist/shares/index.d.ts

@@ -36,7 +36,7 @@ export declare class Shares extends Base {
      */
     shareCreate(params: {
         filter: UID;
-        type: 'song' | 'album' | 'artist';
+        type: 'song' | 'album' | 'artist' | 'playlist' | 'podcast' | 'podcast_episode' | 'video';
         description?: string;
         expires?: number;
     }): Promise<Share>;

package/dist/songs/types.d.ts

@@ -28,6 +28,7 @@ export type Song = {
     album_mbid: string | null;
     artist_mbid: string | null;
     art: string;
+    has_art: boolean;
     flag: boolean;
     rating: number | null;
     averagerating: number | null;

package/dist/system/index.d.ts

@@ -50,6 +50,31 @@ export declare class System extends Base {
     } & Pagination): Promise<{
         list: IndexEntry[];
     }>;
+    /**
+     * This takes a collection of inputs and return ID's for the object type.
+     * @remarks MINIMUM_API_VERSION=6.3.0
+     * @param params.type type of object to find
+     * @param [params.filter] Value is Alpha Match for returned results, may be more than one letter/number
+     * @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] 0, 1, (include child objects)
+     * @param [params.hide_search] 0, 1 (if true do not include searches/smartlists in the result)
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#index}
+     */
+    index(params: {
+        type: 'catalog' | 'song' | 'album' | 'artist' | 'album_artist' | 'song_artist' | 'playlist' | 'podcast' | 'podcast_episode' | 'share' | 'video' | 'live_stream';
+        filter?: string;
+        exact?: BinaryBoolean;
+        add?: Date;
+        update?: Date;
+        include?: BinaryBoolean;
+        hide_search?: BinaryBoolean;
+    } & Pagination): Promise<{
+        index: [];
+    }>;
     /**
      * Return children of a parent object in a folder traversal/browse style
      * If you don't send any parameters you'll get a catalog list (the 'root' path)

package/dist/users/index.d.ts

@@ -10,13 +10,13 @@ export declare class Users extends Base {
         user: UserSummary[];
     }>;
     /**
-     * This get a user's public information
+     * This get a user's public information (or current user if username is omitted)
      * @remarks MINIMUM_API_VERSION=380001
-     * @param params.username UID to find
+     * @param [params.username] UID to find
      * @see {@link https://ampache.org/api/api-json-methods#user}
      */
-    user(params: {
-        username: string;
+    user(params?: {
+        username?: string;
     }): Promise<User>;
     /**
      * Create a new user

package/dist/videos/types.d.ts

@@ -10,6 +10,7 @@ export type Video = {
     time: number;
     url: string;
     art: string;
+    has_art: boolean;
     flag: boolean;
     rating: number | null;
     averagerating: number | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "javascript-ampache",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "A JS library for the Ampache API",
   "main": "dist/index.js",
   "module": "dist/index.m.js",

package/src/albums/types.ts

@@ -24,6 +24,7 @@ export type Album = {
     type: string | null,
     genre: GenreSummary[],
     art: string,
+    has_art: boolean,
     flag: boolean,
     rating: number | null,
     averagerating: number | null,

package/src/artists/types.ts

@@ -20,6 +20,7 @@ export type Artist = {
     songcount: number,
     genre: Genre[],
     art: string,
+    has_art: boolean,
     flag: boolean,
     rating: number | null,
     averagerating: number | null,

package/src/auth/index.ts

@@ -59,7 +59,7 @@ export class Auth extends Base {
     ping (params?: { auth?: string, version?: string }) {
         let query = 'ping';
         query += qs.stringify(params, '&');
-        return this.request<AuthResponse>(query, false);
+        return this.request<AuthResponse>(query);
     }
 
     /**
@@ -68,10 +68,22 @@ export class Auth extends Base {
      * @param params.auth Session ID to destroy
      * @see {@link https://ampache.org/api/api-json-methods#goodbye}
      */
-    goodbye (params: { auth }) {
+    goodbye (params: { auth: string }) {
         let query = 'goodbye';
         query += qs.stringify(params, '&');
-        return this.request<Success>(query, false);
+        return this.request<Success>(query);
+    }
+
+    /**
+     * Email a new password to the user (if allowed) using a reset token.
+     * @remarks MINIMUM_API_VERSION=6.1.0
+     * @param params.auth Password reset token
+     * @see {@link https://ampache.org/api/api-json-methods#lost_password}
+     */
+    lostPassword (params: { auth: string }) {
+        let query = 'lost_password';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
     }
 
     /**

package/src/auth/types.ts

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

package/src/base.ts

@@ -26,7 +26,7 @@ export type UID = string | number;
 export abstract class Base {
     sessionKey: string;
     url: string;
-    version: string = '6.0.0';// default to latest version
+    version: string = '6.3.0';// default to latest version
     debug: boolean;
 
     constructor(config: Config) {
@@ -35,22 +35,22 @@ export abstract class Base {
         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;
-        }
+    protected request<T> (endpoint: string): Promise<T> {
+        let url = this.url + "/server/json.server.php?action=" + endpoint + "&version=" + this.version;
 
         if (this.debug) {
             console.debug(
-                "javascript-ampache query URL %c" + url,
+                "javascript-ampache query URL %c" + url + "&auth=" + this.sessionKey,
                 "color: black; font-style: italic; background-color: orange;padding: 2px"
             );
         }
 
-        return fetch(url).then(r => {
+        return fetch(url, {
+            method: "GET",
+            headers: {
+                'Authorization': 'Bearer ' + this.sessionKey
+            }
+        }).then(r => {
             if (r.ok) {
                 return r.json();
             }
@@ -58,21 +58,22 @@ export abstract class Base {
         })
     }
 
-    protected binary<T> (endpoint: string, includeAuth: boolean = true): Promise<Blob> {
-        let url = this.url + "/server/json.server.php?action=" + endpoint;
-
-        if (includeAuth) {
-            url += "&auth=" + this.sessionKey + "&version=" + this.version;
-        }
+    protected binary<T> (endpoint: string): Promise<Blob> {
+        let url = this.url + "/server/json.server.php?action=" + endpoint + "&version=" + this.version;
 
         if (this.debug) {
             console.debug(
-                "javascript-ampache query URL %c" + url,
+                "javascript-ampache query URL %c" + url + "&auth=" + this.sessionKey,
                 "color: black; font-style: italic; background-color: orange;padding: 2px"
             );
         }
 
-        return fetch(url)
+        return fetch(url,{
+            method: "GET",
+            headers: {
+                'Authorization': 'Bearer ' + this.sessionKey
+            }
+        })
             .then(response => response.blob())
             .then(r => {
                 return r;

package/src/bookmarks/index.ts

@@ -1,15 +1,37 @@
 import qs from 'querystringify';
 import { Bookmark } from './types';
-import { Base, Success, UID } from '../base';
+import { Base, BinaryBoolean, Success, UID } from '../base';
 
 export class Bookmarks extends Base {
+    /**
+     * Get a single bookmark by bookmark_id
+     * @remarks MINIMUM_API_VERSION=6.1.0
+     * @param params.filter UID to find
+     * @param [params.include] 0,1, if true include the object in the bookmark
+     * @see {@link https://ampache.org/api/api-json-methods#bookmark}
+     */
+    async bookmark (params: {
+        filter: UID,
+        include?: BinaryBoolean,
+    }) {
+        let query = 'bookmark';
+        query += qs.stringify(params, '&');
+        return this.request<Bookmark>(query);
+    }
+
     /**
      * Get information about bookmarked media this user is allowed to manage
      * @remarks MINIMUM_API_VERSION=5.0.0
+     * @param [params.client] filter by the agent/client name
+     * @param [params.include] 0,1, if true include the object in the bookmark
      * @see {@link https://ampache.org/api/api-json-methods#bookmarks}
      */
-    async bookmarks () {
+    async bookmarks (params: {
+        client?: string,
+        include?: BinaryBoolean,
+    }) {
         let query = 'bookmarks';
+        query += qs.stringify(params, '&');
         let data = await this.request<{bookmark: Bookmark[]}>(query);
         return (data.bookmark) ? data.bookmark : data;
     }
@@ -19,11 +41,13 @@ export class Bookmarks extends Base {
      * @remarks MINIMUM_API_VERSION=5.0.0
      * @param params.filter UID to find
      * @param params.type Object type
+     * @param [params.include] 0,1, if true include the object in the bookmark
      * @see {@link https://ampache.org/api/api-json-methods#get_bookmark}
      */
     getBookmark (params: {
         filter: UID,
         type: 'song' | 'video' | 'podcast_episode',
+        include?: BinaryBoolean,
     }) {
         let query = 'get_bookmark';
         query += qs.stringify(params, '&');
@@ -38,6 +62,7 @@ export class Bookmarks extends Base {
      * @param params.position current track time in seconds
      * @param [params.client] Agent string. (Default: 'AmpacheAPI')
      * @param [params.date] update time (Default: UNIXTIME())
+     * @param [params.include] 0,1, if true include the object in the bookmark
      * @see {@link https://ampache.org/api/api-json-methods#bookmark_create}
      */
     bookmarkCreate (params: {
@@ -46,6 +71,7 @@ export class Bookmarks extends Base {
         position: number,
         client?: string,
         date?: number,
+        include?: BinaryBoolean,
     }) {
         let query = 'bookmark_create';
         query += qs.stringify(params, '&');
@@ -60,6 +86,7 @@ export class Bookmarks extends Base {
      * @param params.position current track time in seconds
      * @param [params.client] Agent string. (Default: 'AmpacheAPI')
      * @param [params.date] update time (Default: UNIXTIME())
+     * @param [params.include] 0,1, if true include the object in the bookmark
      * @see {@link https://ampache.org/api/api-json-methods#bookmark_edit}
      */
     bookmarkEdit (params: {
@@ -68,6 +95,7 @@ export class Bookmarks extends Base {
         position: number,
         client?: string,
         date?: number,
+        include?: BinaryBoolean,
     }) {
         let query = 'bookmark_edit';
         query += qs.stringify(params, '&');

package/src/playlists/index.ts

@@ -78,6 +78,52 @@ export class Playlists extends Base {
         return this.request<Playlist>(query);
     }
 
+    /**
+     * This returns a user's playlists based on the specified filter
+     * @remarks MINIMUM_API_VERSION=6.3.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#user_playlists}
+     */
+    async userPlaylists (params?: {
+        filter?: string,
+        exact?: BinaryBoolean,
+        add?: Date,
+        update?: Date,
+    } & Pagination) {
+        let query = 'user_playlists';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{playlist: Playlist[]}>(query);
+        return (data.playlist) ? data.playlist : data;
+    }
+
+    /**
+     * This returns a user's smartlists based on the specified filter
+     * @remarks MINIMUM_API_VERSION=6.3.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#user_smartlists}
+     */
+    async userSmartlists (params?: {
+        filter?: string,
+        exact?: BinaryBoolean,
+        add?: Date,
+        update?: Date,
+    } & Pagination) {
+        let query = 'user_smartlists';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{playlist: Playlist[]}>(query);
+        return (data.playlist) ? data.playlist : data;
+    }
+
     /**
      * This creates a new playlist and returns it
      * @remarks MINIMUM_API_VERSION=380001
@@ -94,6 +140,24 @@ export class Playlists extends Base {
         return this.request<Playlist>(query);
     }
 
+    /**
+     * This adds an item to a playlist
+     * @remarks MINIMUM_API_VERSION=6.3.0
+     * @param params.filter UID of Playlist
+     * @param params.id UID of the object to add to playlist
+     * @param params.type 'song', 'album', 'artist', 'playlist'
+     * @see {@link https://ampache.org/api/api-json-methods#playlist_add}
+     */
+    playlistAdd (params: {
+        filter: UID,
+        id: UID,
+        type: 'song' | 'album' | 'artist' | 'playlist',
+    }) {
+        let query = 'playlist_add';
+        query += qs.stringify(params, '&');
+        return this.request<Success>(query);
+    }
+
     /**
      * This modifies name and type of a playlist.
      * NOTE items and tracks must be sent together and be of equal length.
@@ -140,6 +204,7 @@ export class Playlists extends Base {
      * @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}
+     * @deprecated Being removed in 7.0.0. Use `playlist_add` instead.
      */
     playlistAddSong (params: {
         filter: UID,

package/src/playlists/types.ts

@@ -7,6 +7,7 @@ export type Playlist = {
     items: number,
     type: 'public' | 'private',
     art: string,
+    has_art: boolean,
     flag: boolean,
     rating: number | null,
     averagerating: number | null,

package/src/podcasts/types.ts

@@ -13,6 +13,7 @@ export type Podcast = {
     sync_date: string,
     public_url: string,
     art: string,
+    has_art: boolean,
     flag: boolean,
     rating: number | null,
     averaterating: number | null,
@@ -45,6 +46,7 @@ export type PodcastEpisode = {
     url: string,
     catalog: UID,
     art: string,
+    has_art: boolean,
     flag: boolean,
     rating: number | null,
     averagerating: number | null,

package/src/shares/index.ts

@@ -47,7 +47,7 @@ export class Shares extends Base {
      */
     shareCreate (params: {
         filter: UID,
-        type: 'song' | 'album' | 'artist',
+        type: 'song' | 'album' | 'artist' | 'playlist' | 'podcast' | 'podcast_episode' | 'video',
         description?: string,
         expires?: number,
     }) {

package/src/songs/types.ts

@@ -29,6 +29,7 @@ export type Song = {
     album_mbid: string | null,
     artist_mbid: string | null,
     art: string,
+    has_art: boolean,
     flag: boolean,
     rating: number | null,
     averagerating: number | null,

package/src/system/index.ts

@@ -101,6 +101,34 @@ export class System extends Base {
         return this.request<{list: IndexEntry[]}>(query);
     }
 
+    /**
+     * This takes a collection of inputs and return ID's for the object type.
+     * @remarks MINIMUM_API_VERSION=6.3.0
+     * @param params.type type of object to find
+     * @param [params.filter] Value is Alpha Match for returned results, may be more than one letter/number
+     * @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] 0, 1, (include child objects)
+     * @param [params.hide_search] 0, 1 (if true do not include searches/smartlists in the result)
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#index}
+     */
+    async index (params: {
+        type: 'catalog' | 'song' | 'album' | 'artist' | 'album_artist' | 'song_artist' | 'playlist' | 'podcast' | 'podcast_episode' | 'share' | 'video' | 'live_stream'
+        filter?: string,
+        exact?: BinaryBoolean,
+        add?: Date,
+        update?: Date,
+        include?: BinaryBoolean,
+        hide_search?: BinaryBoolean
+    } & Pagination) {
+        let query = 'index';
+        query += qs.stringify(params, '&');
+        return this.request<{index: []}>(query);
+    }
+
     /**
      * Return children of a parent object in a folder traversal/browse style
      * If you don't send any parameters you'll get a catalog list (the 'root' path)

package/src/users/index.ts

@@ -15,13 +15,13 @@ export class Users extends Base {
     }
 
     /**
-     * This get a user's public information
+     * This get a user's public information (or current user if username is omitted)
      * @remarks MINIMUM_API_VERSION=380001
-     * @param params.username UID to find
+     * @param [params.username] UID to find
      * @see {@link https://ampache.org/api/api-json-methods#user}
      */
-    async user (params: {
-        username: string
+    async user (params?: {
+        username?: string
     }) {
         let query = 'user';
         query += qs.stringify(params, '&');

package/src/videos/types.ts

@@ -11,6 +11,7 @@ export type Video = {
     time: number,
     url: string,
     art: string,
+    has_art: boolean,
     flag: boolean,
     rating: number | null,
     averagerating: number | null,