javascript-ampache 1.1.9 → 1.2.0

package/dist/playlists/index.d.ts

@@ -57,6 +57,7 @@ export declare class Playlists extends Base {
      * 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.include] 0, 1 (include playlist items)
      * @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
@@ -68,6 +69,7 @@ export declare class Playlists extends Base {
      */
     userPlaylists(params?: {
         filter?: string;
+        include?: BinaryBoolean;
         exact?: BinaryBoolean;
         add?: Date;
         update?: Date;
@@ -76,6 +78,7 @@ export declare class Playlists extends Base {
      * 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.include] 0, 1 (include playlist items)
      * @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
@@ -87,6 +90,7 @@ export declare class Playlists extends Base {
      */
     userSmartlists(params?: {
         filter?: string;
+        include?: BinaryBoolean;
         exact?: BinaryBoolean;
         add?: Date;
         update?: Date;

package/dist/songs/index.d.ts

@@ -108,10 +108,13 @@ export declare class Songs extends Base {
     /**
      * Get the full song file tags using VaInfo
      * This is used to get tags for remote catalogs to allow maximum data to be returned
-     * @remarks MINIMUM_API_VERSION=7.5.0
+     * @remarks MINIMUM_API_VERSION=6.7.0
      * @param params.filter UID of song to fetch
      * @see {@link https://ampache.org/api/api-json-methods#song_tags}
      */
+    songTags(params: {
+        filter: UID;
+    }): Promise<unknown>;
     /**
      * This takes a URL and returns the song object in question
      * @remarks MINIMUM_API_VERSION=380001

package/dist/system/index.d.ts

@@ -1,5 +1,5 @@
 import { Base, BinaryBoolean, ExtendedPagination, Pagination, Success, UID } from "../base";
-import { IndexEntry, NowPlayingResponse } from "./types";
+import { IndexEntry, NowPlayingResponse, RuleResponse } from "./types";
 export declare class System extends Base {
     /**
      * Check Ampache for updates and run the update if there is one.
@@ -102,6 +102,7 @@ export declare class System extends Base {
         catalog?: number;
         add?: Date;
         update?: Date;
+        cond?: string;
     } & ExtendedPagination): Promise<{
         browse: IndexEntry[];
     }>;
@@ -361,6 +362,17 @@ export declare class System extends Base {
     }): Promise<{
         now_playing: NowPlayingResponse[];
     }>;
+    /**
+     * Print a list of valid search rules for your search type
+     * @remarks MINIMUM_API_VERSION=6.8.0
+     * @param params.filter Object type
+     * @see {@link https://ampache.org/api/api-json-methods#search_rules}
+     */
+    searchRules(params: {
+        filter: "song" | "album" | "song_artist" | "album_artist" | "artist" | "label" | "playlist" | "podcast" | "podcast_episode" | "genre" | "user" | "video";
+    }): Promise<{
+        rule: RuleResponse[];
+    }>;
     /**
      * Perform an advanced search given passed rules.
      * You'll want to consult the docs for this.

package/dist/system/types.d.ts

@@ -22,3 +22,10 @@ export type NowPlayingResponse = {
     expire: number;
     user: UserSummary;
 };
+export type RuleResponse = {
+    name: string;
+    label: string;
+    type: string;
+    title: string;
+    widget: string[];
+};

package/dist/utils.d.ts

@@ -1,2 +1,4 @@
+import { Base } from "./base";
 export declare function applyMixins(derivedCtor: any, baseCtors: any[]): void;
 export declare function encryptPassword(password: string, time: number): string;
+export declare function outputDebugURL(url: string, config: Base): void;

package/package.json

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

package/src/auth/index.ts

@@ -3,6 +3,7 @@ import qs from "querystringify";
 import fetch from "isomorphic-unfetch";
 import { Base, Success } from "../base";
 import { AuthResponse } from "./types";
+import { outputDebugURL } from "../utils";
 
 export class Auth extends Base {
   /**
@@ -20,6 +21,8 @@ export class Auth extends Base {
     timestamp?: number;
     version?: string;
   }) {
+    let token = params.auth;
+
     // generate a timestamp if one wasn't provided
     if (!params.timestamp) {
       params.timestamp = Math.floor(new Date().getTime() / 1000);
@@ -35,10 +38,22 @@ export class Auth extends Base {
       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, "&");
 
-    return fetch(query)
+    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) {

package/src/base.ts

@@ -1,10 +1,11 @@
 import fetch from "isomorphic-unfetch";
 import qs from "querystringify";
+import { outputDebugURL } from "./utils";
 
 type Config = {
   url: string;
   sessionKey?: string;
-  useBearerToken: false;
+  useBearerToken?: boolean;
   debug?: boolean;
 };
 
@@ -51,7 +52,6 @@ export abstract class Base {
   }
 
   protected request<T>(endpoint: string): Promise<T> {
-    let authString = "&auth=" + this.sessionKey;
     let url =
       this.url +
       "/server/json.server.php?action=" +
@@ -60,21 +60,16 @@ export abstract class Base {
       this.version;
 
     if (!this.useBearerToken) {
-      url += authString;
+      url += "&auth=" + this.sessionKey;
     }
 
     if (this.debug) {
-      console.debug(
-        "javascript-ampache query URL %c" + url,
-        "color: black; font-style: italic; background-color: orange;padding: 2px",
-      );
+      outputDebugURL(url, this);
     }
 
     return fetch(url, {
       method: "GET",
-      headers: {
-        Authorization: this.useBearerToken ? "Bearer " + this.sessionKey : undefined,
-      },
+      headers: this.useBearerToken ? { Authorization: "Bearer " + this.sessionKey } : {},
     }).then((r) => {
       if (r.ok) {
         return r.json();
@@ -84,28 +79,22 @@ export abstract class Base {
   }
 
   protected binary<T>(endpoint: string): Promise<Blob> {
-    let authString = "&auth=" + this.sessionKey;
     let url =
       this.url +
       "/server/json.server.php?action=" + endpoint +
       "&version=" + this.version;
 
     if (!this.useBearerToken) {
-      url += authString;
+      url += "&auth=" + this.sessionKey;
     }
 
     if (this.debug) {
-      console.debug(
-        "javascript-ampache query URL %c" + url,
-        "color: black; font-style: italic; background-color: orange;padding: 2px",
-      );
+      outputDebugURL(url, this);
     }
 
     return fetch(url, {
       method: "GET",
-      headers: {
-        Authorization: this.useBearerToken ? "Bearer " + this.sessionKey : undefined,
-      },
+      headers: this.useBearerToken ? { Authorization: "Bearer " + this.sessionKey } : {},
     })
       .then((response) => response.blob())
       .then((r) => {
@@ -123,7 +112,6 @@ export abstract class Base {
    * @param [params]
    */
   public rawURL(endpoint: string, params?: {}) {
-    let authString = "&auth=" + this.sessionKey;
     let query = endpoint;
     query += qs.stringify(params, "&");
 
@@ -133,14 +121,11 @@ export abstract class Base {
       "&version=" + this.version;
 
     if (!this.useBearerToken) {
-      url += authString;
+      url += "&auth=" + this.sessionKey;
     }
 
     if (this.debug) {
-      console.debug(
-        "javascript-ampache query URL %c" + url,
-        "color: black; font-style: italic; background-color: orange;padding: 2px",
-      );
+      outputDebugURL(url, this);
     }
 
     return url;

package/src/playlists/index.ts

@@ -89,6 +89,7 @@ export class Playlists extends Base {
    * 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.include] 0, 1 (include playlist items)
    * @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
@@ -101,6 +102,7 @@ export class Playlists extends Base {
   userPlaylists(
     params?: {
       filter?: string;
+      include?: BinaryBoolean;
       exact?: BinaryBoolean;
       add?: Date;
       update?: Date;
@@ -115,6 +117,7 @@ export class Playlists extends Base {
    * 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.include] 0, 1 (include playlist items)
    * @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
@@ -127,6 +130,7 @@ export class Playlists extends Base {
   userSmartlists(
     params?: {
       filter?: string;
+      include?: BinaryBoolean;
       exact?: BinaryBoolean;
       add?: Date;
       update?: Date;

package/src/songs/index.ts

@@ -165,15 +165,15 @@ export class Songs extends Base {
   /**
    * Get the full song file tags using VaInfo
    * This is used to get tags for remote catalogs to allow maximum data to be returned
-   * @remarks MINIMUM_API_VERSION=7.5.0
+   * @remarks MINIMUM_API_VERSION=6.7.0
    * @param params.filter UID of song to fetch
    * @see {@link https://ampache.org/api/api-json-methods#song_tags}
    */
-  // songTags(params: { filter: UID }) {
-  //   let query = "song_tags";
-  //   query += qs.stringify(params, "&");
-  //   return this.request<SongResponse>(query); // TODO update reponse
-  // }
+  songTags(params: { filter: UID }) {
+    let query = "song_tags";
+    query += qs.stringify(params, "&");
+    return this.request(query); // TODO response type
+  }
 
   /**
    * This takes a URL and returns the song object in question

package/src/system/index.ts

@@ -22,7 +22,7 @@ import { LiveStreamsResponse } from "../live-streams/types";
 import { LabelResponse, LabelsResponse } from "../labels/types";
 import { GenreResponse, GenresResponse } from "../genres/types";
 import { UserResponse, UsersResponse } from "../users/types";
-import { IndexEntry, NowPlayingResponse } from "./types";
+import { IndexEntry, NowPlayingResponse, RuleResponse } from "./types";
 
 export class System extends Base {
   /**
@@ -209,6 +209,7 @@ export class System extends Base {
       catalog?: number;
       add?: Date;
       update?: Date;
+      cond?: string;
     } & ExtendedPagination,
   ) {
     let query = "browse";
@@ -637,6 +638,20 @@ export class System extends Base {
     return this.request<{ now_playing: NowPlayingResponse[] }>(query);
   }
 
+  /**
+   * Print a list of valid search rules for your search type
+   * @remarks MINIMUM_API_VERSION=6.8.0
+   * @param params.filter Object type
+   * @see {@link https://ampache.org/api/api-json-methods#search_rules}
+   */
+  searchRules(params: {
+    filter: "song" | "album" | "song_artist" | "album_artist" | "artist" | "label" | "playlist" | "podcast" | "podcast_episode" | "genre" | "user" | "video";
+  }) {
+    let query = "search_rules";
+    query += qs.stringify(params, "&");
+    return this.request<{ rule: RuleResponse[] }>(query);
+  }
+
   /**
    * Perform an advanced search given passed rules.
    * You'll want to consult the docs for this.

package/src/system/types.ts

@@ -39,4 +39,12 @@ export type NowPlayingResponse = {
   client: string;
   expire: number;
   user: UserSummary;
+}
+
+export type RuleResponse = {
+  name: string;
+  label: string;
+  type: string;
+  title: string;
+  widget: string[];
 }

package/src/utils.ts

@@ -1,25 +1,40 @@
-import JsSHA from "jssha/dist/sha256";
-
-export function applyMixins(derivedCtor: any, baseCtors: any[]) {
-  baseCtors.forEach((baseCtor) => {
-    Object.getOwnPropertyNames(baseCtor.prototype).forEach((name) => {
-      Object.defineProperty(
-        derivedCtor.prototype,
-        name,
-        Object.getOwnPropertyDescriptor(baseCtor.prototype, name),
-      );
-    });
-  });
-}
-
-export function encryptPassword(password: string, time: number) {
-  let key = getSHA256(password);
-  return getSHA256(time + key);
-
-  function getSHA256(text) {
-    let shaObj = new JsSHA("SHA-256", "TEXT", { encoding: "UTF8" });
-    shaObj.update(text);
-
-    return shaObj.getHash("HEX");
-  }
-}
+import JsSHA from "jssha/dist/sha256";
+import { Base } from "./base";
+
+export function applyMixins(derivedCtor: any, baseCtors: any[]) {
+  baseCtors.forEach((baseCtor) => {
+    Object.getOwnPropertyNames(baseCtor.prototype).forEach((name) => {
+      Object.defineProperty(
+        derivedCtor.prototype,
+        name,
+        Object.getOwnPropertyDescriptor(baseCtor.prototype, name),
+      );
+    });
+  });
+}
+
+export function encryptPassword(password: string, time: number) {
+  let key = getSHA256(password);
+  return getSHA256(time + key);
+
+  function getSHA256(text) {
+    let shaObj = new JsSHA("SHA-256", "TEXT", { encoding: "UTF8" });
+    shaObj.update(text);
+
+    return shaObj.getHash("HEX");
+  }
+}
+
+export function outputDebugURL(url: string, config: Base) {
+  let label = "javascript-ampache query URL";
+
+  if (config.useBearerToken) {
+    label = "(Using Bearer token, auth added for debugging) - " + label;
+    url += "&auth=" + config.sessionKey;
+  }
+
+  console.debug(
+      label + " %c" + url,
+      "color: black; font-style: italic; background-color: orange;padding: 2px",
+  );
+}