javascript-ampache 0.0.1

package/dist/system/index.d.ts

@@ -0,0 +1,267 @@
+import { Base, BinaryBoolean, Pagination, Success, UID } from '../base';
+export declare class System extends Base {
+    /**
+     * Check Ampache for updates and run the update if there is one.
+     * @remarks MINIMUM_API_VERSION=5.0.0
+     * @see {@link https://ampache.org/api/api-json-methods#system_update}
+     */
+    systemUpdate(): Promise<Success>;
+    /**
+     * This takes a collection of inputs and returns ID + name for the object type
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.type type of object to find
+     * @param [params.filter] search the name of the object_type
+     * @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 songs in a playlist or episodes in a podcast)
+     * @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#get_indexes}
+     */
+    getIndexes(params: {
+        type: 'song' | 'album' | 'artist' | 'album_artist' | 'playlist' | 'podcast' | 'podcast_episode' | 'live_stream';
+        filter?: string;
+        add?: Date;
+        update?: Date;
+        include?: BinaryBoolean;
+        hide_search?: number;
+    } & Pagination): Promise<any>;
+    /**
+     * Return similar artist IDs or similar song IDs compared to the input filter
+     * @remarks MINIMUM_API_VERSION=420000
+     * @param params.type type of object to check against
+     * @param params.filter UID to find
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#get_similar}
+     */
+    getSimilar(params: {
+        type: 'song' | 'artist';
+        filter: UID;
+    } & Pagination): Promise<any>;
+    /**
+     * Get some items based on some simple search types and filters. (Random by default)
+     * @remarks MINIMUM_API_VERSION=380001; CHANGED_IN_API_VERSION=400001
+     * @param params.type Object type
+     * @param [params.filter] newest, highest, frequent, recent, forgotten, flagged, random
+     * @param [params.user_id] Filter results to a certain user by UID
+     * @param [params.username] Filter results to a certain user by username
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#stats}
+     */
+    stats(params: {
+        type: 'song' | 'album' | 'artist' | 'video' | 'playlist' | 'podcast' | 'podcast_episode';
+        filter?: 'newest' | 'highest' | 'frequent' | 'recent' | 'forgotten' | 'flagged' | 'random';
+        user_id?: number;
+        username?: string;
+    } & Pagination): Promise<any>;
+    /**
+     * This rates a library item
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param params.type Object type
+     * @param params.id UID to find
+     * @param params.rating Rating to apply
+     * @see {@link https://ampache.org/api/api-json-methods#rate}
+     */
+    rate(params: {
+        type: 'song' | 'album' | 'artist' | 'playlist' | 'podcast' | 'podcast_episode' | 'video' | 'tvshow' | 'tvshow_season';
+        id: UID;
+        rating: 0 | 1 | 2 | 3 | 4 | 5;
+    }): Promise<Success>;
+    /**
+     * This flags a library item as a favorite
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.type Object type
+     * @param params.id UID to find
+     * @param params.flag 0, 1
+     * @see {@link https://ampache.org/api/api-json-methods#flag}
+     */
+    flag(params: {
+        type: 'song' | 'album' | 'artist' | 'playlist' | 'podcast' | 'podcast_episode' | 'video' | 'tvshow' | 'tvshow_season';
+        id: UID;
+        flag: BinaryBoolean;
+    }): Promise<Success>;
+    /**
+     * Take a song_id and update the object_count and user_activity table with a play. This allows other sources to record play history to Ampache.
+     * If you don't supply a user id (optional) then just fall back to you.
+     * ACCESS REQUIRED: 100 (Admin) permission to change another user's play history
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.id UID of song
+     * @param [params.user] UID of user
+     * @param [params.client] Client string
+     * @param [params.date] UNIXTIME
+     * @see {@link https://ampache.org/api/api-json-methods#record_play}
+     */
+    recordPlay(params: {
+        id: UID;
+        user?: UID;
+        client?: string;
+        date?: number;
+    }): Promise<Success>;
+    /**
+     * Search for a song using text info and then record a play if found. This allows other sources to record play history to ampache
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.song HTML encoded string
+     * @param params.artist HTML encoded string
+     * @param params.album HTML encoded string
+     * @param [params.songmbid] Song MBID
+     * @param [params.artistmbid] Artist MBID
+     * @param [params.albummbid] Album MBID
+     * @param [params.song_mbid] Alias of songmbid
+     * @param [params.artist_mbid] Alias of artistmbid
+     * @param [params.album_mbid] Alias of albummbid
+     * @param [params.date] UNIXTIME
+     * @param [params.client] Client string
+     * @see {@link https://ampache.org/api/api-json-methods#scrobble}
+     */
+    scrobble(params: {
+        song: string;
+        artist: string;
+        album: string;
+        songmbid?: string;
+        artistmbid?: string;
+        albummbid?: string;
+        song_mbid?: string;
+        artist_mbid?: string;
+        album_mbid?: string;
+        date?: number;
+        client?: string;
+    }): Promise<Success>;
+    /**
+     * Update a single album, artist, song from the tag data
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.type Object type
+     * @param params.id UID to find
+     * @see {@link https://ampache.org/api/api-json-methods#update_from_tags}
+     */
+    updateFromTags(params: {
+        type: 'song' | 'artist' | 'album';
+        id: UID;
+    }): Promise<Success>;
+    /**
+     * Update artist information and fetch similar artists from last.fm
+     * Make sure lastfm_API_key is set in your configuration file
+     * ACCESS REQUIRED: 75 (Catalog Manager)
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.id UID to find
+     * @see {@link https://ampache.org/api/api-json-methods#update_artist_info}
+     */
+    updateArtistInfo(params: {
+        id: UID;
+    }): Promise<Success>;
+    /**
+     * Updates a single album, artist, song running the gather_art process.
+     * Doesn't overwrite existing art by default.
+     * ACCESS REQUIRED: 75 (Catalog Manager)
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.id UID to update
+     * @param params.type Object type
+     * @param [params.overwrite]
+     * @see {@link https://ampache.org/api/api-json-methods#update_art}
+     */
+    updateArt(params: {
+        id: UID;
+        type: 'artist' | 'album' | 'song';
+        overwrite?: BinaryBoolean;
+    }): Promise<Success>;
+    /**
+     * Streams a given media file. Takes the file id in parameter with optional max bit rate, file format, time offset,
+     * size and estimate content length option.
+     * NOTE search and playlist will only stream a random object from the list.
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.id UID to find
+     * @param params.type Object type
+     * @param [params.bitrate] Max bitrate for transcoding
+     * @param [params.format] mp3, ogg, raw, etc (raw returns the original format)
+     * @param [params.offset] Time offset
+     * @param [params.length] 0, 1 (estimate content length)
+     * @see {@link https://ampache.org/api/api-json-methods#stream}
+     */
+    stream(params: {
+        id: UID;
+        type: 'song' | 'podcast_episode' | 'search' | 'playlist';
+        bitrate?: number;
+        format?: string;
+        offset?: number;
+        length?: BinaryBoolean;
+    }): Promise<unknown>;
+    /**
+     * Downloads a given media file. set format=raw to download the full file
+     * NOTE search and playlist will only download a random object from the list
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.id UID to find
+     * @param params.type Object type
+     * @param [params.format] mp3, ogg, raw, etc (raw returns the original format)
+     * @see {@link https://ampache.org/api/api-json-methods#download}
+     */
+    download(params: {
+        id: UID;
+        type: 'song' | 'podcast_episode' | 'search' | 'playlist';
+        format?: string;
+    }): Promise<unknown>;
+    /**
+     * Get an art image file.
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.id UID to find
+     * @param params.type Object type
+     * @see {@link https://ampache.org/api/api-json-methods#get_art}
+     */
+    getArt(params: {
+        id: UID;
+        type: 'song' | 'artist' | 'album' | 'playlist' | 'search' | 'podcast';
+    }): Promise<unknown>;
+    /**
+     * This is for controlling localplay
+     * @param params.command The command to send to the localplay controller
+     * @param [params.oid] Object UID
+     * @param [params.type] Object type
+     * @param [params.clear] 0, 1 (Clear the current playlist before adding)
+     * @remarks MINIMUM_API_VERSION=380001; CHANGED_IN_API_VERSION=5.0.0
+     * @see {@link https://ampache.org/api/api-json-methods#localplay}
+     */
+    localplay(params: {
+        command: 'next' | 'prev' | 'stop' | 'play' | 'pause' | 'add' | 'volume_up' | 'volume_down' | 'volume_mute' | 'delete_all' | 'skip' | 'status';
+        oid?: number;
+        type?: 'song' | 'video' | 'podcast_episode' | 'channel' | 'broadcast' | 'democratic' | 'live_stream';
+        clear?: BinaryBoolean;
+    }): Promise<unknown>;
+    /**
+     * Get the list of songs in your localplay playlist
+     * @remarks MINIMUM_API_VERSION=5.0.0
+     * @see {@link https://ampache.org/api/api-json-methods#localplay_songs}
+     */
+    localplaySongs(): Promise<unknown>;
+    /**
+     * This is for controlling democratic play (Songs only). VOTE: +1 vote for the oid. DEVOTE: -1 vote for the oid.
+     * PLAYLIST: Return an array of song items with an additional VOTE COUNT element.
+     * PLAY: Returns the URL for playing democratic play.
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param params.oid UID of song
+     * @param params.method vote, devote, playlist, play
+     * @see {@link https://ampache.org/api/api-json-methods#democratic}
+     */
+    democratic(params: {
+        oid: UID;
+        method: 'vote' | 'devote' | 'playlist' | 'play';
+    }): Promise<unknown>;
+    /**
+     * Perform an advanced search given passed rules.
+     * You'll want to consult the docs for this.
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param params.operator and, or (whether to match one rule or all)
+     * @param params.type Object type to return
+     * @param params.rules An array of rules
+     * @param [params.random] 0, 1 (random order of results; default to 0)
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#advanced_search}
+     */
+    advancedSearch(params: {
+        operator: 'and' | 'or';
+        type: 'song' | 'album' | 'artist' | 'label' | 'playlist' | 'podcast' | 'podcast_episode' | 'genre' | 'user' | 'video';
+        rules: Array<Array<string>>;
+        random?: BinaryBoolean;
+    } & Pagination): Promise<any>;
+}

package/dist/system/types.d.ts

@@ -0,0 +1,9 @@
+import { Song } from "../songs/types";
+import { Album } from "../albums/types";
+import { Artist } from "../artists/types";
+import { Playlist } from "../playlists/types";
+import { Podcast, PodcastEpisode } from "../podcasts/types";
+import { LiveStream } from "../live-streams/types";
+import { Video } from "../videos/types";
+export type IndexType = Song | Album | Artist | Playlist | Podcast | PodcastEpisode | LiveStream;
+export type StatsType = Song | Album | Artist | Video | Playlist | Podcast | PodcastEpisode;

package/dist/users/index.d.ts

@@ -0,0 +1,134 @@
+import { User, UserSummary, Activity } from './types';
+import { Base, BinaryBoolean, Success } from '../base';
+export declare class Users extends Base {
+    /**
+     * Get ids and usernames for your site
+     * @remarks MINIMUM_API_VERSION=5.0.0
+     * @see {@link https://ampache.org/api/api-json-methods#users}
+     */
+    users(): Promise<UserSummary[] | {
+        user: UserSummary[];
+    }>;
+    /**
+     * This get a user's public information
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param params.username UID to find
+     * @see {@link https://ampache.org/api/api-json-methods#user}
+     */
+    user(params: {
+        username: string;
+    }): Promise<User>;
+    /**
+     * Create a new user
+     * ACCESS REQUIRED: 100 (Admin)
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.username Username
+     * @param params.password SHA256 hashed password
+     * @param params.email  Email
+     * @param [params.fullname] Full Name
+     * @param [params.disable] 0, 1
+     * @param [params.catalog_filter_group] Catalog filter group, default = 0
+     * @see {@link https://ampache.org/api/api-json-methods#user_create}
+     */
+    userCreate(params: {
+        username: string;
+        password: string;
+        email: string;
+        fullname?: string;
+        disable?: BinaryBoolean;
+        catalog_filter_group?: number;
+    }): Promise<Success>;
+    /**
+     * Update an existing user
+     * ACCESS REQUIRED: 100 (Admin)
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param  params.username Username
+     * @param  [params.password] Password
+     * @param  [params.email] Email
+     * @param  [params.fullname] Full Name
+     * @param  [params.website] Website
+     * @param  [params.state] State
+     * @param  [params.city] City
+     * @param  [params.disable] 0, 1
+     * @param  [params.maxbitrate] Max bitrate for transcoding
+     * @see {@link https://ampache.org/api/api-json-methods#user_update}
+     */
+    userUpdate(params: {
+        username: string;
+        password?: string;
+        email?: string;
+        fullname?: string;
+        website?: string;
+        state?: string;
+        city?: string;
+        disable?: BinaryBoolean;
+        maxbitrate?: string;
+    }): Promise<Success>;
+    /**
+     * Delete an existing user.
+     * ACCESS REQUIRED: 100 (Admin)
+     * @remarks MINIMUM_API_VERSION=400001
+     * @param params.filter UID of user to delete
+     * @see {@link https://ampache.org/api/api-json-methods#user_delete}
+     */
+    userDelete(params: {
+        filter: string;
+    }): Promise<Success>;
+    /**
+     * This gets the followers for the requested username
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param params.username UID to find
+     * @see {@link https://ampache.org/api/api-json-methods#followers}
+     */
+    followers(params: {
+        username: string;
+    }): Promise<UserSummary[] | {
+        user: UserSummary[];
+    }>;
+    /**
+     * Get a list of people that this user follows
+     * @remarks MINIMUM_API_VERSION=380001
+     * @see {@link https://ampache.org/api/api-json-methods#following}
+     */
+    following(params: {
+        username: string;
+    }): Promise<UserSummary[] | {
+        user: UserSummary[];
+    }>;
+    /**
+     * This will follow/unfollow a user
+     * @param params.username Username string to find
+     * @see {@link https://ampache.org/api/api-json-methods#toggle_follow}
+     */
+    toggleFollow(params: {
+        username: string;
+    }): Promise<Success>;
+    /**
+     * This get a user timeline
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param params.username Username to find
+     * @param [params.limit] Max results to return
+     * @param [params.since] UNIXTIME
+     * @see {@link https://ampache.org/api/api-json-methods#timeline}
+     */
+    timeline(params: {
+        username: string;
+        limit?: number;
+        since?: number;
+    }): Promise<Activity[] | {
+        activity: Activity[];
+    }>;
+    /**
+     * This get current user friends timeline
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param [params.limit] Max results to return
+     * @param [params.since] UNIXTIME
+     * @see {@link https://ampache.org/api/api-json-methods#friends_timeline}
+     */
+    friendsTimeline(params?: {
+        limit?: number;
+        since?: number;
+    }): Promise<Activity[] | {
+        activity: Activity[];
+    }>;
+}

package/dist/users/types.d.ts

@@ -0,0 +1,29 @@
+import { UID } from "../base";
+export type UserSummary = {
+    id: UID;
+    username: string;
+};
+export type User = {
+    id: UID;
+    username: string;
+    auth: string;
+    email: string;
+    access: number;
+    streamtoken: string | null;
+    fullname_public: number;
+    validation: string | null;
+    disabled: boolean;
+    create_date: number;
+    last_seen: number;
+    website: string | null;
+    state: string | null;
+    city: string | null;
+};
+export type Activity = {
+    id: UID;
+    date: number;
+    object_type: string;
+    object_id: UID;
+    action: string;
+    user: UserSummary;
+};

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function applyMixins(derivedCtor: any, baseCtors: any[]): void;
+export declare function encryptPassword(password: string, time: number): string;

package/dist/videos/index.d.ts

@@ -0,0 +1,37 @@
+import { Video, DeletedVideo } from './types';
+import { Base, BinaryBoolean, Pagination, UID } from '../base';
+export declare class Videos extends Base {
+    /**
+     * Get videos
+     * @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.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#videos}
+     */
+    videos(params?: {
+        filter?: string;
+        exact?: BinaryBoolean;
+    } & Pagination): Promise<Video[] | {
+        video: Video[];
+    }>;
+    /**
+     * This returns a single video
+     * @remarks MINIMUM_API_VERSION=380001
+     * @param params.filter UID to find
+     * @see {@link https://ampache.org/api/api-json-methods#video}
+     */
+    video(params: {
+        filter: UID;
+    }): Promise<Video>;
+    /**
+     * This returns video objects that have been deleted
+     * @param [params.offset]
+     * @param [params.limit]
+     * @see {@link https://ampache.org/api/api-json-methods#deleted_videos}
+     */
+    deletedVideos(params?: {} & Pagination): Promise<DeletedVideo[] | {
+        deleted_video: DeletedVideo[];
+    }>;
+}

package/dist/videos/types.d.ts

@@ -0,0 +1,27 @@
+import { UID } from "../base";
+import { GenreSummary } from "../genres/types";
+export type Video = {
+    id: UID;
+    title: string;
+    mime: string;
+    resolution: string;
+    size: number;
+    genre: GenreSummary[];
+    time: number;
+    url: string;
+    art: string;
+    flag: boolean;
+    rating: number | null;
+    averagerating: number | null;
+    playcount: number;
+};
+export type DeletedVideo = {
+    id: UID;
+    addition_time: number;
+    delete_time: number;
+    title: string;
+    file: string;
+    catalog: UID;
+    total_count: number;
+    total_skip: number;
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "javascript-ampache",
+  "version": "0.0.1",
+  "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",
+  "repository": "github:mitchray/javascript-ampache",
+  "scripts": {
+    "build": "rimraf dist && microbundle --tsconfig tsconfig.json",
+    "dev": "microbundle watch --tsconfig tsconfig.json",
+    "test": "jest"
+  },
+  "devDependencies": {
+    "@types/jest": "^25.2.1",
+    "jest": "^29.3.1",
+    "microbundle": "0.13.0",
+    "nock": "^12.0.3",
+    "rimraf": "^4.1.1"
+  },
+  "keywords": [
+    "ampache",
+    "javascript",
+    "typescript",
+    "api",
+    "js"
+  ],
+  "author": "mitchray (https://github.com/mitchray)",
+  "license": "GPL-3.0-only",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "dependencies": {
+    "isomorphic-unfetch": "3.1.0",
+    "jssha": "^3.3.0",
+    "querystringify": "2.2.0"
+  }
+}

package/src/albums/index.ts

@@ -0,0 +1,80 @@
+import qs from 'querystringify';
+import { Album } from './types';
+import { Base, BinaryBoolean, Pagination, UID } from '../base';
+
+export 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]
+     * @see {@link https://ampache.org/api/api-json-methods#albums}
+     */
+    async albums (params?: {
+        filter?: number,
+        exact?: BinaryBoolean,
+        add?: Date,
+        update?: Date,
+        include?: "albums" | "songs",
+    } & Pagination) {
+        let query = 'albums';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{album: Album[]}>(query);
+        return (data.album) ? data.album : data;
+    }
+
+    /**
+     * 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'
+    }) {
+        let query = 'album';
+        query += qs.stringify(params, '&');
+        return this.request<Album>(query);
+    }
+
+    /**
+     * This returns the albums of an artist
+     * @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#artist_albums}
+     */
+    async artistAlbums (params: {
+        filter: UID
+    } & Pagination) {
+        let query = 'artist_albums';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{album: Album[]}>(query);
+        return (data.album) ? data.album : data;
+    }
+
+    /**
+     * 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]
+     * @see {@link https://ampache.org/api/api-json-methods#genre_albums}
+     */
+    async genreAlbums (params?: {
+        filter: UID
+    } & Pagination) {
+        let query = 'genre_albums';
+        query += qs.stringify(params, '&');
+        let data = await this.request<{album: Album[]}>(query);
+        return (data.album) ? data.album : data;
+    }
+}

package/src/albums/types.ts

@@ -0,0 +1,31 @@
+import { UID } from '../base';
+import { GenreSummary } from "../genres/types";
+import { ArtistSummary } from "../artists/types";
+import { Song } from "../songs/types";
+
+export type AlbumSummary = {
+    id: UID,
+    name: string,
+    prefix: string | null,
+    basename: string,
+}
+
+export type Album = {
+    id: UID,
+    name: string,
+    prefix: string | null,
+    basename: string,
+    artist: ArtistSummary,
+    time: number,
+    year: number | string,
+    tracks?: Song[],
+    songcount: number,
+    disccount: number,
+    type: string | null,
+    genre: GenreSummary[],
+    art: string,
+    flag: boolean,
+    rating: number | null,
+    averagerating: number | null,
+    mbid: string | null
+}