javascript-ampache 1.2.0 → 2.0.0

package/src/users.js

@@ -0,0 +1,224 @@
+/**
+ * @typedef {Object} UserSummary
+ * @property {import("./base.js").UID} id
+ * @property {string} username
+ */
+
+/**
+ * @typedef {Object} UserResponse
+ * @property {import("./base.js").UID} id
+ * @property {string} username
+ * @property {string} auth
+ * @property {string} email
+ * @property {number} access
+ * @property {string|null} streamtoken
+ * @property {number} fullname_public
+ * @property {string|null} validation
+ * @property {boolean} disabled
+ * @property {number} create_date
+ * @property {number} last_seen
+ * @property {string|null} website
+ * @property {string|null} state
+ * @property {string|null} city
+ */
+
+/**
+ * @typedef {Object} UsersResponse
+ * @property {number} total_count
+ * @property {string} md5
+ * @property {UserResponse[]} user
+ */
+
+/**
+ * @typedef {Object} ActivityResponse
+ * @property {import("./base.js").UID} id
+ * @property {number} date
+ * @property {string} object_type
+ * @property {import("./base.js").UID} object_id
+ * @property {string} action
+ * @property {UserSummary} user
+ */
+
+export const usersMethods = {
+  /**
+   * Get ids and usernames for your site
+   * @remarks MINIMUM_API_VERSION=5.0.0
+   * @returns {Promise<{ user: UserSummary[] }>}
+   * @see {@link https://ampache.org/api/api-json-methods#users}
+   */
+  users() {
+    return this.call("users");
+  },
+
+  /**
+   * This get a user's public information (or current user if username is omitted)
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} [params]
+   * @param {string} [params.username] Username of the user to get details for
+   * @returns {Promise<UserResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#user}
+   */
+  user(params) {
+    return this.call("user", params);
+  },
+
+  /**
+   * Create a new user
+   * ACCESS REQUIRED: 100 (Admin)
+   * @remarks MINIMUM_API_VERSION=400001
+   * @param {Object} params
+   * @param {string} params.username Username
+   * @param {string} params.password SHA256 hashed password
+   * @param {string} params.email  Email
+   * @param {string} [params.fullname] Full Name
+   * @param {import("./base.js").BinaryBoolean} [params.disable] 0, 1
+   * @param {number} [params.group] Catalog filter group (API param: group), default = 0
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#user_create}
+   */
+  userCreate(params) {
+    return this.call("user_create", params);
+  },
+
+  /**
+   * Register as a new user if allowed.
+   * @remarks MINIMUM_API_VERSION=6.0.0
+   * @param {Object} params
+   * @param {string} params.username Username
+   * @param {string} params.password SHA256 hashed password
+   * @param {string} params.email  Email
+   * @param {string} [params.fullname] Full Name
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods/#register}
+   */
+  register(params) {
+    return this.call("register", params);
+  },
+
+  /**
+   * Update an existing user
+   * ACCESS REQUIRED: 100 (Admin)
+   * @remarks MINIMUM_API_VERSION=400001
+   * @param {Object} params
+   * @param {string} params.username Username
+   * @param {string} [params.password] Password
+   * @param {string} [params.email] Email
+   * @param {string} [params.fullname] Full Name
+   * @param {string} [params.website] Website
+   * @param {string} [params.state] State
+   * @param {string} [params.city] City
+   * @param {import("./base.js").BinaryBoolean} [params.disable] 0, 1
+   * @param {string} [params.maxbitrate] Max bitrate for transcoding
+   * @returns {Promise<import("./base.js").Success>}
+   * @deprecated Being removed in 7.0.0. Use `user_edit` instead.
+   * @see {@link https://ampache.org/api/api-json-methods#user_update}
+   */
+  userUpdate(params) {
+    return this.call("user_update", params);
+  },
+
+  /**
+   * Update an existing user
+   * ACCESS REQUIRED: 100 (Admin)
+   * @remarks MINIMUM_API_VERSION=6.0.0
+   * @param {Object} params
+   * @param {string} params.username Username
+   * @param {string} [params.password] Password
+   * @param {string} [params.email] Email
+   * @param {string} [params.fullname] Full Name
+   * @param {string} [params.website] Website
+   * @param {string} [params.state] State
+   * @param {string} [params.city] City
+   * @param {string} [params.maxbitrate] Max bitrate for transcoding
+   * @param {number} [params.group] Catalog filter group, default = 0
+   * @param {import("./base.js").BinaryBoolean} [params.disable] 0, 1
+   * @param {import("./base.js").BinaryBoolean} [params.fullname_public] show fullname in public display
+   * @param {import("./base.js").BinaryBoolean} [params.reset_apikey] reset user Api Key
+   * @param {import("./base.js").BinaryBoolean} [params.reset_streamtoken] reset user Stream Token
+   * @param {import("./base.js").BinaryBoolean} [params.clear_stats] reset all stats for this user
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#user_edit}
+   */
+  userEdit(params) {
+    return this.call("user_edit", params);
+  },
+
+  /**
+   * Delete an existing user.
+   * ACCESS REQUIRED: 100 (Admin)
+   * @remarks MINIMUM_API_VERSION=400001
+   * @param {Object} params
+   * @param {string} params.username Username of user to delete (required by API)
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#user_delete}
+   */
+  userDelete(params) {
+    return this.call("user_delete", params);
+  },
+
+  /**
+   * This gets the followers for the requested username
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} params
+   * @param {string} params.username UID to find
+   * @param {number} [params.offset]
+   * @param {number} [params.limit]
+   * @param {string} [params.cond]
+   * @param {string} [params.sort]
+   * @returns {Promise<{ user: UserSummary[] }>}
+   * @see {@link https://ampache.org/api/api-json-methods#followers}
+   */
+  followers(params) {
+    return this.call("followers", params);
+  },
+
+  /**
+   * Get a list of people that this user follows
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} params
+   * @param {string} params.username
+   * @returns {Promise<{ user: UserSummary[] }>}
+   * @see {@link https://ampache.org/api/api-json-methods#following}
+   */
+  following(params) {
+    return this.call("following", params);
+  },
+
+  /**
+   * This will follow/unfollow a user
+   * @param {Object} params
+   * @param {string} params.username Username string to find
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#toggle_follow}
+   */
+  toggleFollow(params) {
+    return this.call("toggle_follow", params);
+  },
+
+  /**
+   * This get a user timeline
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} params
+   * @param {string} params.username Username to find
+   * @param {number} [params.limit] Max results to return
+   * @param {number} [params.since] UNIXTIME
+   * @returns {Promise<{ activity: ActivityResponse[] }>}
+   * @see {@link https://ampache.org/api/api-json-methods#timeline}
+   */
+  timeline(params) {
+    return this.call("timeline", params);
+  },
+
+  /**
+   * This get current user friends timeline
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} [params]
+   * @param {number} [params.limit] Max results to return
+   * @param {number} [params.since] UNIXTIME
+   * @returns {Promise<{ activity: ActivityResponse[] }>}
+   * @see {@link https://ampache.org/api/api-json-methods#friends_timeline}
+   */
+  friendsTimeline(params) {
+    return this.call("friends_timeline", params);
+  },
+};

package/src/{utils.ts → utils.js}

@@ -1,22 +1,18 @@
 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) {
+/**
+ * @param {string} password
+ * @param {number} time
+ * @returns {string}
+ */
+export function encryptPassword(password, time) {
   let key = getSHA256(password);
   return getSHA256(time + key);
 
+  /**
+   * @param {string} text
+   * @returns {string}
+   */
   function getSHA256(text) {
     let shaObj = new JsSHA("SHA-256", "TEXT", { encoding: "UTF8" });
     shaObj.update(text);
@@ -25,7 +21,11 @@ export function encryptPassword(password: string, time: number) {
   }
 }
 
-export function outputDebugURL(url: string, config: Base) {
+/**
+ * @param {string} url
+ * @param {{ useBearerToken?: boolean, sessionKey?: string|null }} config
+ */
+export function outputDebugURL(url, config) {
   let label = "javascript-ampache query URL";
 
   if (config.useBearerToken) {
@@ -37,4 +37,4 @@ export function outputDebugURL(url: string, config: Base) {
       label + " %c" + url,
       "color: black; font-style: italic; background-color: orange;padding: 2px",
   );
-}
+}

package/src/videos.js

@@ -0,0 +1,84 @@
+/**
+ * @typedef {Object} VideoResponse
+ * @property {import("./base.js").UID} id
+ * @property {string} title
+ * @property {string} mime
+ * @property {string} resolution
+ * @property {number} size
+ * @property {import("./genres.js").GenreSummary[]} genre
+ * @property {number} time
+ * @property {string} url
+ * @property {string} art
+ * @property {boolean} has_art
+ * @property {boolean} flag
+ * @property {number|null} rating
+ * @property {number|null} averagerating
+ * @property {number} playcount
+ */
+
+/**
+ * @typedef {Object} VideosResponse
+ * @property {number} total_count
+ * @property {string} md5
+ * @property {VideoResponse[]} video
+ */
+
+/**
+ * @typedef {Object} DeletedVideoResponse
+ * @property {import("./base.js").UID} id
+ * @property {number} addition_time
+ * @property {number} delete_time
+ * @property {string} title
+ * @property {string} file
+ * @property {import("./base.js").UID} catalog
+ * @property {number} total_count
+ * @property {number} total_skip
+ */
+
+/**
+ * @typedef {Object} DeletedVideosResponse
+ * @property {number} total_count
+ * @property {string} md5
+ * @property {DeletedVideoResponse[]} deleted_video
+ */
+
+export const videosMethods = {
+  /**
+   * Get videos
+   * @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 {number} [params.offset]
+   * @param {number} [params.limit]
+   * @returns {Promise<VideosResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#videos}
+   */
+  videos(params) {
+    return this.call("videos", params);
+  },
+
+  /**
+   * This returns a single video
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID to find
+   * @returns {Promise<VideoResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#video}
+   */
+  video(params) {
+    return this.call("video", params);
+  },
+
+  /**
+   * This returns video objects that have been deleted
+   * @param {Object} [params]
+   * @param {number} [params.offset]
+   * @param {number} [params.limit]
+   * @returns {Promise<DeletedVideosResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#deleted_videos}
+   */
+  deletedVideos(params) {
+    return this.call("deleted_videos", params);
+  },
+};

package/dist/albums/index.d.ts

@@ -1,64 +0,0 @@
-import { AlbumResponse, AlbumsResponse } from "./types";
-import { Base, BinaryBoolean, ExtendedPagination, UID } from "../base";
-export declare class Albums extends Base {
-    /**
-     * This returns albums based on the provided search filters
-     * @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.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.offset]
-     * @param [params.limit]
-     * @param [params.cond]
-     * @param [params.sort]
-     * @see {@link https://ampache.org/api/api-json-methods#albums}
-     */
-    albums(params?: {
-        filter?: number;
-        exact?: BinaryBoolean;
-        add?: Date;
-        update?: Date;
-        include?: "albums" | "songs";
-    } & ExtendedPagination): Promise<AlbumsResponse>;
-    /**
-     * This returns a single album based on the UID provided
-     * @remarks MINIMUM_API_VERSION=380001
-     * @param params.filter UID to find
-     * @param [params.include] songs (include child objects in the response)
-     * @see {@link https://ampache.org/api/api-json-methods#album}
-     */
-    album(params: {
-        filter: UID;
-        include?: "songs";
-    }): Promise<AlbumResponse>;
-    /**
-     * This returns the albums of an artist
-     * @remarks MINIMUM_API_VERSION=380001
-     * @param params.filter UID to find
-     * @param [params.album_artist] 0, 1 (if true filter for album artists only)
-     * @param [params.offset]
-     * @param [params.limit]
-     * @param [params.cond]
-     * @param [params.sort]
-     * @see {@link https://ampache.org/api/api-json-methods#artist_albums}
-     */
-    artistAlbums(params: {
-        filter: UID;
-        album_artist?: BinaryBoolean;
-    } & ExtendedPagination): Promise<AlbumsResponse>;
-    /**
-     * This returns the albums associated with the genre in question
-     * @remarks MINIMUM_API_VERSION=380001
-     * @param params.filter UID to find
-     * @param [params.offset]
-     * @param [params.limit]
-     * @param [params.cond]
-     * @param [params.sort]
-     * @see {@link https://ampache.org/api/api-json-methods#genre_albums}
-     */
-    genreAlbums(params?: {
-        filter: UID;
-    } & ExtendedPagination): Promise<AlbumsResponse>;
-}

package/dist/albums/types.d.ts

@@ -1,37 +0,0 @@
-import { UID } from "../base";
-import { GenreSummary } from "../genres/types";
-import { ArtistSummary } from "../artists/types";
-import { SongResponse } from "../songs/types";
-export type AlbumSummary = {
-    id: UID;
-    name: string;
-    prefix: string | null;
-    basename: string;
-};
-export type AlbumResponse = {
-    id: UID;
-    name: string;
-    prefix: string | null;
-    basename: string;
-    artist: ArtistSummary;
-    artists: ArtistSummary[];
-    songartists: ArtistSummary[];
-    time: number;
-    year: number | string;
-    tracks?: SongResponse[];
-    songcount: number;
-    disccount: number;
-    type: string | null;
-    genre: GenreSummary[];
-    art: string;
-    has_art: boolean;
-    flag: boolean;
-    rating: number | null;
-    averagerating: number | null;
-    mbid: string | null;
-};
-export type AlbumsResponse = {
-    total_count: number;
-    md5: string;
-    album: AlbumResponse[];
-};

package/dist/artists/index.d.ts

@@ -1,64 +0,0 @@
-import { ArtistResponse, ArtistsResponse } from "./types";
-import { Base, BinaryBoolean, ExtendedPagination, UID } from "../base";
-export declare 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]
-     * @param [params.cond]
-     * @param [params.sort]
-     * @see {@link https://ampache.org/api/api-json-methods#artists}
-     */
-    artists(params?: {
-        filter?: string;
-        exact?: BinaryBoolean;
-        add?: Date;
-        update?: Date;
-        include?: "albums" | "songs";
-        album_artist?: BinaryBoolean;
-    } & ExtendedPagination): Promise<ArtistsResponse>;
-    /**
-     * 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";
-    }): Promise<ArtistResponse>;
-    /**
-     * 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]
-     * @param [params.cond]
-     * @param [params.sort]
-     * @see {@link https://ampache.org/api/api-json-methods#genre_artists}
-     */
-    genreArtists(params: {
-        filter: UID;
-    } & ExtendedPagination): Promise<ArtistsResponse>;
-    /**
-     * 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]
-     * @param [params.cond]
-     * @param [params.sort]
-     * @see {@link https://ampache.org/api/api-json-methods#label_artists}
-     */
-    labelArtists(params: {
-        filter: UID;
-    } & ExtendedPagination): Promise<ArtistsResponse>;
-}

package/dist/artists/types.d.ts

@@ -1,35 +0,0 @@
-import { AlbumResponse } from "../albums/types";
-import { SongsResponse } from "../songs/types";
-import { GenreResponse } from "../genres/types";
-export type ArtistSummary = {
-    id: string;
-    name: string;
-    prefix: string | null;
-    basename: string;
-};
-export type ArtistResponse = {
-    id: string;
-    name: string;
-    prefix: string | null;
-    basename: string;
-    albums: AlbumResponse[];
-    albumcount: number;
-    songs: SongsResponse[];
-    songcount: number;
-    genre: GenreResponse[];
-    art: string;
-    has_art: boolean;
-    flag: boolean;
-    rating: number | null;
-    averagerating: number | null;
-    mbid: string | null;
-    summary: string;
-    time: number;
-    yearformed: number;
-    placeformed: string;
-};
-export type ArtistsResponse = {
-    total_count: number;
-    md5: string;
-    artist: ArtistResponse[];
-};

package/dist/auth/index.d.ts

@@ -1,56 +0,0 @@
-import { Base, Success } from "../base";
-import { AuthResponse } from "./types";
-export declare 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;
-    }): Promise<AuthResponse>;
-    /**
-     * 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;
-    }): Promise<AuthResponse>;
-    /**
-     * 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: string;
-    }): Promise<Success>;
-    /**
-     * 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;
-    }): Promise<Success>;
-    /**
-     * Encrypt your password into the accepted format.
-     */
-    encryptPassword(params: {
-        password: string;
-        time: number;
-    }): string;
-}

package/dist/auth/types.d.ts

@@ -1,32 +0,0 @@
-export type AuthResponse = {
-    add: string;
-    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;
-    podcasts: number;
-    podcast_episodes: number;
-    server: string;
-    session_expire: string;
-    shares: number;
-    songs: number;
-    update: string;
-    user: number;
-    username: string;
-    version: string;
-    videos: number;
-    max_song: number;
-    max_album: number;
-    max_artist: number;
-    max_video: number;
-    max_podcast: number;
-    max_podcast_episode: number;
-};