javascript-ampache 1.1.10 → 2.0.0

package/package.json

@@ -1,31 +1,32 @@
 {
   "name": "javascript-ampache",
-  "version": "1.1.10",
+  "version": "2.0.0",
   "description": "A JS library for the Ampache API",
   "main": "dist/index.js",
   "module": "dist/index.m.js",
   "umd:main": "dist/index.umd.js",
-  "source": "src/index.ts",
+  "source": "src/index.js",
   "repository": "github:mitchray/javascript-ampache",
   "scripts": {
-    "build": "rimraf dist && microbundle --tsconfig tsconfig.json",
-    "dev": "microbundle watch --tsconfig tsconfig.json",
+    "build": "rimraf dist && microbundle",
+    "dev": "microbundle watch",
     "test": "jest"
   },
   "devDependencies": {
-    "@types/jest": "^25.2.3",
+    "@babel/preset-env": "^7.29.0",
+    "babel-jest": "^30.2.0",
     "isomorphic-unfetch": "^3.1.0",
     "jest": "^29.3.1",
     "jssha": "^3.3.0",
     "microbundle": "^0.15.1",
     "nock": "^13.0.0",
+    "node-fetch": "^2.7.0",
     "querystringify": "2.2.0",
     "rimraf": "^5.0.0"
   },
   "keywords": [
     "ampache",
     "javascript",
-    "typescript",
     "api",
     "js"
   ],
@@ -35,4 +36,4 @@
     "src",
     "dist"
   ]
-}
+}

package/src/albums.js

@@ -0,0 +1,106 @@
+/**
+ * @typedef {Object} AlbumSummary
+ * @property {import("./base.js").UID} id
+ * @property {string} name
+ * @property {string|null} prefix
+ * @property {string} basename
+ */
+
+/**
+ * @typedef {Object} AlbumResponse
+ * @property {import("./base.js").UID} id
+ * @property {string} name
+ * @property {string|null} prefix
+ * @property {string} basename
+ * @property {import("./artists.js").ArtistSummary} artist
+ * @property {import("./artists.js").ArtistSummary[]} artists
+ * @property {import("./artists.js").ArtistSummary[]} songartists
+ * @property {number} time
+ * @property {number|string} year
+ * @property {import("./songs.js").SongResponse[]} [tracks]
+ * @property {number} songcount
+ * @property {number} disccount
+ * @property {string|null} type
+ * @property {import("./genres.js").GenreSummary[]} genre
+ * @property {string} art
+ * @property {boolean} has_art
+ * @property {boolean} flag
+ * @property {number|null} rating
+ * @property {number|null} averagerating
+ * @property {string|null} mbid
+ */
+
+/**
+ * @typedef {Object} AlbumsResponse
+ * @property {number} total_count
+ * @property {string} md5
+ * @property {AlbumResponse[]} album
+ */
+
+export const albumsMethods = {
+  /**
+   * This returns albums based on the provided search filters
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} [params]
+   * @param {string} [params.filter] Filter results to match this string
+   * @param {import("./base.js").BinaryBoolean} [params.exact] 0, 1 (if true filter is exact = rather than fuzzy LIKE)
+   * @param {Date} [params.add] ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date
+   * @param {Date} [params.update] ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date
+   * @param {"albums"|"songs"} [params.include] albums, songs (include child objects in the response)
+   * @param {number} [params.offset]
+   * @param {number} [params.limit]
+   * @param {string} [params.cond]
+   * @param {string} [params.sort]
+   * @returns {Promise<AlbumsResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#albums}
+   */
+  albums(params) {
+    return this.call("albums", params);
+  },
+
+  /**
+   * This returns a single album based on the UID provided
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID to find
+   * @param {"songs"} [params.include] songs (include child objects in the response)
+   * @returns {Promise<AlbumResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#album}
+   */
+  album(params) {
+    return this.call("album", params);
+  },
+
+  /**
+   * This returns the albums of an artist
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID to find
+   * @param {import("./base.js").BinaryBoolean} [params.album_artist] 0, 1 (if true filter for album artists only)
+   * @param {number} [params.offset]
+   * @param {number} [params.limit]
+   * @param {string} [params.cond]
+   * @param {string} [params.sort]
+   * @returns {Promise<AlbumsResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#artist_albums}
+   */
+  artistAlbums(params) {
+    return this.call("artist_albums", params);
+  },
+
+  /**
+   * This returns the albums associated with the genre in question
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} [params]
+   * @param {import("./base.js").UID} [params.filter] UID to find
+   * @param {number} [params.offset]
+   * @param {number} [params.limit]
+   * @param {string} [params.cond]
+   * @param {string} [params.sort]
+   * @returns {Promise<AlbumsResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#genre_albums}
+   */
+  genreAlbums(params) {
+    return this.call("genre_albums", params);
+  },
+};

package/src/artists.js

@@ -0,0 +1,105 @@
+/**
+ * @typedef {Object} ArtistSummary
+ * @property {string} id
+ * @property {string} name
+ * @property {string|null} prefix
+ * @property {string} basename
+ */
+
+/**
+ * @typedef {Object} ArtistResponse
+ * @property {string} id
+ * @property {string} name
+ * @property {string|null} prefix
+ * @property {string} basename
+ * @property {import("./albums.js").AlbumResponse[]} albums
+ * @property {number} albumcount
+ * @property {import("./songs.js").SongsResponse[]} songs
+ * @property {number} songcount
+ * @property {import("./genres.js").GenreResponse[]} genre
+ * @property {string} art
+ * @property {boolean} has_art
+ * @property {boolean} flag
+ * @property {number|null} rating
+ * @property {number|null} averagerating
+ * @property {string|null} mbid
+ * @property {string} summary
+ * @property {number} time
+ * @property {number} yearformed
+ * @property {string} placeformed
+ */
+
+/**
+ * @typedef {Object} ArtistsResponse
+ * @property {number} total_count
+ * @property {string} md5
+ * @property {ArtistResponse[]} artist
+ */
+
+export const artistsMethods = {
+  /**
+   * This takes a collection of inputs and returns artist objects
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} [params]
+   * @param {string} [params.filter] Filter results to match this string
+   * @param {import("./base.js").BinaryBoolean} [params.exact] 0, 1 (if true filter is exact = rather than fuzzy LIKE)
+   * @param {Date} [params.add] ISO 8601 Date Format (2020-09-16) Find objects with an 'add' date newer than the specified date
+   * @param {Date} [params.update] ISO 8601 Date Format (2020-09-16) Find objects with an 'update' time newer than the specified date
+   * @param {"albums"|"songs"} [params.include] (albums | songs) include child objects in the response
+   * @param {import("./base.js").BinaryBoolean} [params.album_artist] 0, 1 (if true filter for album artists only)
+   * @param {number} [params.offset]
+   * @param {number} [params.limit]
+   * @param {string} [params.cond]
+   * @param {string} [params.sort]
+   * @returns {Promise<ArtistsResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#artists}
+   */
+  artists(params) {
+    return this.call("artists", params);
+  },
+
+  /**
+   * This returns a single artist based on the UID of said artist
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID to find
+   * @param {"albums"|"songs"} [params.include] (albums | songs) include child objects in the response
+   * @returns {Promise<ArtistResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#artist}
+   */
+  artist(params) {
+    return this.call("artist", params);
+  },
+
+  /**
+   * This returns the artists associated with the genre in question as defined by the UID
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID to find
+   * @param {number} [params.offset]
+   * @param {number} [params.limit]
+   * @param {string} [params.cond]
+   * @param {string} [params.sort]
+   * @returns {Promise<ArtistsResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#genre_artists}
+   */
+  genreArtists(params) {
+    return this.call("genre_artists", params);
+  },
+
+  /**
+   * This returns the artists associated with the label in question as defined by the UID
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID of find
+   * @param {number} [params.offset]
+   * @param {number} [params.limit]
+   * @param {string} [params.cond]
+   * @param {string} [params.sort]
+   * @returns {Promise<ArtistsResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#label_artists}
+   */
+  labelArtists(params) {
+    return this.call("label_artists", params);
+  },
+};

package/src/auth.js

@@ -0,0 +1,142 @@
+/**
+ * @typedef {Object} AuthResponse
+ * @property {string} add
+ * @property {number} albums
+ * @property {string} api
+ * @property {number} artists
+ * @property {string} auth
+ * @property {number} catalogs
+ * @property {string} compatible
+ * @property {string} clean
+ * @property {number} genres
+ * @property {number} labels
+ * @property {number} licenses
+ * @property {number} live_streams
+ * @property {number} playlists
+ * @property {number} podcasts
+ * @property {number} podcast_episodes
+ * @property {string} server
+ * @property {string} session_expire
+ * @property {number} shares
+ * @property {number} songs
+ * @property {string} update
+ * @property {number} user
+ * @property {string} username
+ * @property {string} version
+ * @property {number} videos
+ * @property {number} max_song
+ * @property {number} max_album
+ * @property {number} max_artist
+ * @property {number} max_video
+ * @property {number} max_podcast
+ * @property {number} max_podcast_episode
+ */
+
+import qs from "querystringify";
+import fetch from "isomorphic-unfetch";
+import { outputDebugURL, encryptPassword as encryptPasswordUtil } from "./utils.js";
+
+export const authMethods = {
+  /**
+   * Handles verifying a new handshake
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} params
+   * @param {string} params.auth encrypted apikey OR password if using password auth
+   * @param {string} [params.user] username
+   * @param {number} [params.timestamp] UNIXTIME()
+   * @param {string} [params.version] version of Ampache API to establish connection with
+   * @returns {Promise<AuthResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#handshake}
+   */
+  handshake(params) {
+    let token = params.auth;
+
+    // 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;
+    }
+
+    // not needed if using Bearer token
+    if (this.useBearerToken) {
+      delete params.auth;
+    }
+
+    let query = this.url + "/server/json.server.php?action=handshake";
+    query += qs.stringify(params, "&");
+
+    if (this.debug) {
+      outputDebugURL(query, this);
+    }
+
+    return fetch(query, {
+      method: "GET",
+      headers: this.useBearerToken ? { Authorization: "Bearer " + token } : {},
+    })
+      .then((response) => response.json())
+      .then((data) => {
+        if (data.auth) {
+          this.sessionKey = data.auth;
+        }
+        return /** @type {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 {Object} [params]
+   * @param {string} [params.auth] (Session ID) returns version information and extends the session if passed
+   * @param {string} [params.version] API Version that the application understands
+   * @returns {Promise<AuthResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#ping}
+   */
+  ping(params) {
+    return this.call("ping", params);
+  },
+
+  /**
+   * Destroy a session using the session auth parameter
+   * @remarks MINIMUM_API_VERSION=400001
+   * @param {Object} params
+   * @param {string} params.auth Session ID to destroy
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#goodbye}
+   */
+  goodbye(params) {
+    return this.call("goodbye", params);
+  },
+
+  /**
+   * Email a new password to the user (if allowed) using a reset token.
+   * @remarks MINIMUM_API_VERSION=6.1.0
+   * @param {Object} params
+   * @param {string} params.auth Password reset token
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#lost_password}
+   */
+  lostPassword(params) {
+    return this.call("lost_password", params);
+  },
+
+  /**
+   * Encrypt your password into the accepted format.
+   * @param {Object} params
+   * @param {string} params.password
+   * @param {number} params.time
+   * @returns {string}
+   */
+  encryptPassword(params) {
+    return encryptPasswordUtil(params.password, params.time);
+  },
+};

package/src/base.js

@@ -0,0 +1,145 @@
+import fetch from "isomorphic-unfetch";
+import qs from "querystringify";
+import { outputDebugURL } from "./utils.js";
+
+/**
+ * @typedef {Object} Config
+ * @property {string} url
+ * @property {string} [sessionKey]
+ * @property {boolean} [useBearerToken]
+ * @property {boolean} [debug]
+ */
+
+/**
+ * @typedef {Object} Success
+ * @property {string} success
+ */
+
+/**
+ * @typedef {Object} Pagination
+ * @property {number} [offset] Return results starting from this index position
+ * @property {number} [limit] Maximum number of results to return
+ */
+
+/**
+ * @typedef {Object} ExtendedPagination
+ * @property {number} [offset] Return results starting from this index position
+ * @property {number} [limit] Maximum number of results to return
+ * @property {string} [cond] Apply additional filters to the browse using ; separated comma string pairs (e.g. 'filter1,value1;filter2,value2')
+ * @property {string} [sort] Sort name or comma-separated key pair. (e.g. 'name,order') Default order 'ASC' (e.g. 'name,ASC' == 'name')
+ */
+
+/** @typedef {0|1} BinaryBoolean */
+
+/** @typedef {string|number} UID */
+
+export class Base {
+  /**
+   * @param {Config} config
+   */
+  constructor(config) {
+    this.sessionKey = config.sessionKey || null;
+    this.url = config.url;
+    this.version = "6.6.8";
+    this.useBearerToken = config.useBearerToken || false;
+    this.debug = config.debug || false;
+  }
+
+  /**
+   * Build action string with optional params and call request.
+   * @template T
+   * @param {string} action API action name
+   * @param {Object} [params] Optional query params
+   * @returns {Promise<T>}
+   */
+  call(action, params) {
+    const query = action + (params != null ? qs.stringify(params, "&") : "");
+    return this.request(query);
+  }
+
+  /**
+   * @param {string} endpoint Action and optional query string
+   * @returns {string} Full request URL
+   * @private
+   */
+  _buildURL(endpoint) {
+    let url =
+      this.url +
+      "/server/json.server.php?action=" +
+      endpoint +
+      "&version=" +
+      this.version;
+
+    if (!this.useBearerToken) {
+      url += "&auth=" + this.sessionKey;
+    }
+
+    if (this.debug) {
+      outputDebugURL(url, this);
+    }
+
+    return url;
+  }
+
+  /**
+   * @template T
+   * @param {string} endpoint
+   * @returns {Promise<T>}
+   */
+  request(endpoint) {
+    const url = this._buildURL(endpoint);
+    return fetch(url, {
+      method: "GET",
+      headers: this.useBearerToken ? { Authorization: "Bearer " + this.sessionKey } : {},
+    }).then(async (r) => {
+      if (r.ok) {
+        return r.json();
+      }
+      let body = r.statusText;
+      const contentType = r.headers.get("content-type");
+      try {
+        body = contentType && contentType.includes("application/json")
+          ? await r.json()
+          : await r.text();
+      } catch (_) {
+        // keep statusText if body read fails
+      }
+      const err = new Error(r.statusText);
+      err.status = r.status;
+      err.body = body;
+      throw err;
+    });
+  }
+
+  /**
+   * @param {string} endpoint
+   * @returns {Promise<Blob>}
+   */
+  binary(endpoint) {
+    const url = this._buildURL(endpoint);
+    return fetch(url, {
+      method: "GET",
+      headers: this.useBearerToken ? { Authorization: "Bearer " + this.sessionKey } : {},
+    }).then((response) => response.blob());
+  }
+
+  /**
+   * @param {string} sessionKey
+   */
+  setSessionKey(sessionKey) {
+    this.sessionKey = sessionKey;
+  }
+
+  /**
+   * Construct and return a URL
+   * @param {string} endpoint
+   * @param {Object} [params]
+   * @returns {string}
+   */
+  rawURL(endpoint, params) {
+    const query = endpoint + (params != null ? qs.stringify(params, "&") : "");
+    return this._buildURL(query);
+  }
+}
+
+export {};

package/src/bookmarks.js

@@ -0,0 +1,106 @@
+/**
+ * @typedef {Object} BookmarkResponse
+ * @property {import("./base.js").UID} id
+ * @property {"song"|"video"|"podcast_episode"} type
+ * @property {number} position
+ * @property {string} [client]
+ * @property {number} [date]
+ */
+
+/**
+ * @typedef {Object} BookmarksResponse
+ * @property {number} total_count
+ * @property {string} md5
+ * @property {BookmarkResponse[]} bookmark
+ */
+
+export const bookmarksMethods = {
+  /**
+   * Get a single bookmark by bookmark_id
+   * @remarks MINIMUM_API_VERSION=6.1.0
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID to find
+   * @param {import("./base.js").BinaryBoolean} [params.include] 0,1, if true include the object in the bookmark
+   * @returns {Promise<BookmarkResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#bookmark}
+   */
+  bookmark(params) {
+    return this.call("bookmark", params);
+  },
+
+  /**
+   * Get information about bookmarked media this user is allowed to manage
+   * @remarks MINIMUM_API_VERSION=5.0.0
+   * @param {Object} [params]
+   * @param {string} [params.client] filter by the agent/client name
+   * @param {import("./base.js").BinaryBoolean} [params.include] 0,1, if true include the object in the bookmark
+   * @returns {Promise<BookmarksResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#bookmarks}
+   */
+  bookmarks(params) {
+    return this.call("bookmarks", params);
+  },
+
+  /**
+   * Get the bookmark/s from its object_id and object_type.
+   * @remarks MINIMUM_API_VERSION=5.0.0
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID to find
+   * @param {"song"|"video"|"podcast_episode"} params.type Object type
+   * @param {import("./base.js").BinaryBoolean} [params.include] 0,1, if true include the object in the bookmark
+   * @param {import("./base.js").BinaryBoolean} [params.all]
+   * @returns {Promise<BookmarkResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#get_bookmark}
+   */
+  getBookmark(params) {
+    return this.call("get_bookmark", params);
+  },
+
+  /**
+   * Create a placeholder for the current media that you can return to later.
+   * @remarks MINIMUM_API_VERSION=5.0.0
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID to find
+   * @param {"song"|"video"|"podcast_episode"} params.type Object type
+   * @param {number} params.position current track time in seconds
+   * @param {string} [params.client] Agent string. (Default: 'AmpacheAPI')
+   * @param {number} [params.date] update time (Default: UNIXTIME())
+   * @param {import("./base.js").BinaryBoolean} [params.include] 0,1, if true include the object in the bookmark
+   * @returns {Promise<BookmarkResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#bookmark_create}
+   */
+  bookmarkCreate(params) {
+    return this.call("bookmark_create", params);
+  },
+
+  /**
+   * Edit a placeholder for the current media that you can return to later.
+   * @remarks MINIMUM_API_VERSION=5.0.0
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID to find
+   * @param {"bookmark"|"song"|"video"|"podcast_episode"} params.type Object type
+   * @param {number} params.position current track time in seconds
+   * @param {string} [params.client] Agent string. (Default: 'AmpacheAPI')
+   * @param {number} [params.date] update time (Default: UNIXTIME())
+   * @param {import("./base.js").BinaryBoolean} [params.include] 0,1, if true include the object in the bookmark
+   * @returns {Promise<BookmarkResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#bookmark_edit}
+   */
+  bookmarkEdit(params) {
+    return this.call("bookmark_edit", params);
+  },
+
+  /**
+   * Delete an existing bookmark. (if it exists)
+   * @remarks MINIMUM_API_VERSION=5.0.0
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID to find
+   * @param {"song"|"video"|"podcast_episode"} params.type Object type
+   * @param {string} [params.client] Agent string. (Default: 'AmpacheAPI')
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#bookmark_delete}
+   */
+  bookmarkDelete(params) {
+    return this.call("bookmark_delete", params);
+  },
+};