javascript-ampache 1.2.0 → 2.0.0

package/src/podcasts.js

@@ -0,0 +1,230 @@
+/**
+ * @typedef {Object} PodcastEpisodeResponse
+ * @property {import("./base.js").UID} id
+ * @property {string} title
+ * @property {string} name
+ * @property {string} description
+ * @property {string} category
+ * @property {string} author
+ * @property {string} author_full
+ * @property {string} website
+ * @property {string} pubdate
+ * @property {"completed"|"pending"} state
+ * @property {string} filelength
+ * @property {string} filesize
+ * @property {string} filename
+ * @property {string} mime
+ * @property {number} time
+ * @property {number} size
+ * @property {number} bitrate
+ * @property {number} stream_bitrate
+ * @property {number} rate
+ * @property {number|null} mode
+ * @property {number|null} channels
+ * @property {string} public_url
+ * @property {string} url
+ * @property {import("./base.js").UID} catalog
+ * @property {string} art
+ * @property {boolean} has_art
+ * @property {boolean} flag
+ * @property {number|null} rating
+ * @property {number|null} averagerating
+ * @property {number} playcount
+ * @property {number} played
+ */
+
+/**
+ * @typedef {Object} PodcastResponse
+ * @property {import("./base.js").UID} id
+ * @property {string} name
+ * @property {string} description
+ * @property {string} language
+ * @property {string} copyright
+ * @property {string} feed_url
+ * @property {string} generator
+ * @property {string} website
+ * @property {string} build_date
+ * @property {string} sync_date
+ * @property {string} public_url
+ * @property {string} art
+ * @property {boolean} has_art
+ * @property {boolean} flag
+ * @property {number|null} rating
+ * @property {number|null} averaterating
+ * @property {PodcastEpisodeResponse[]} podcast_episode
+ */
+
+/**
+ * @typedef {Object} PodcastsResponse
+ * @property {number} total_count
+ * @property {string} md5
+ * @property {PodcastResponse[]} podcast
+ */
+
+/**
+ * @typedef {Object} PodcastEpisodesResponse
+ * @property {number} total_count
+ * @property {string} md5
+ * @property {PodcastEpisodeResponse[]} podcast_episode
+ */
+
+/**
+ * @typedef {Object} DeletedPodcastEpisodeResponse
+ * @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
+ * @property {import("./base.js").UID} podcast
+ */
+
+/**
+ * @typedef {Object} DeletedPodcastEpisodesResponse
+ * @property {number} total_count
+ * @property {string} md5
+ * @property {DeletedPodcastEpisodeResponse[]} deleted_podcast_episode
+ */
+
+export const podcastsMethods = {
+  /**
+   * Get information about podcasts
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} [params]
+   * @param {string} [params.filter] Value is Alpha Match for returned results, may be more than one letter/number
+   * @param {"episodes"} [params.include] episodes (include podcast_episodes in the response)
+   * @param {number} [params.offset]
+   * @param {number} [params.limit]
+   * @param {string} [params.cond]
+   * @param {string} [params.sort]
+   * @returns {Promise<PodcastsResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#podcasts}
+   */
+  podcasts(params) {
+    return this.call("podcasts", params);
+  },
+
+  /**
+   * Get the podcast from its id
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID of podcast, returns podcast JSON
+   * @param {"episodes"} [params.include] episodes (include podcast_episodes in the response)
+   * @returns {Promise<PodcastResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#podcast}
+   */
+  podcast(params) {
+    return this.call("podcast", params);
+  },
+
+  /**
+   * Create a podcast that can be used by anyone to stream media.
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} params
+   * @param {string} params.url RSS url for podcast
+   * @param {import("./base.js").UID} params.catalog UID of podcast catalog
+   * @returns {Promise<PodcastResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#podcast_create}
+   */
+  podcastCreate(params) {
+    return this.call("podcast_create", params);
+  },
+
+  /**
+   * Update the description and/or expiration date for an existing podcast.
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID to find
+   * @param {string} [params.feed] RSS url for podcast
+   * @param {string} [params.title] Podcast title
+   * @param {string} [params.website] Source website URL
+   * @param {string} [params.description] Podcast description
+   * @param {string} [params.generator] Podcast generator
+   * @param {string} [params.copyright] Podcast copyright
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#podcast_edit}
+   */
+  podcastEdit(params) {
+    return this.call("podcast_edit", params);
+  },
+
+  /**
+   * Delete an existing podcast
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID of podcast to delete
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#podcast_delete}
+   */
+  podcastDelete(params) {
+    return this.call("podcast_delete", params);
+  },
+
+  /**
+   * This returns the episodes for a podcast
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID of podcast
+   * @param {number} [params.offset]
+   * @param {number} [params.limit]
+   * @param {string} [params.cond]
+   * @param {string} [params.sort]
+   * @returns {Promise<PodcastEpisodesResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#podcast_episodes}
+   */
+  podcastEpisodes(params) {
+    return this.call("podcast_episodes", params);
+  },
+
+  /**
+   * Get the podcast_episode from a UID
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID of podcast
+   * @returns {Promise<PodcastEpisodeResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#podcast_episode}
+   */
+  podcastEpisode(params) {
+    return this.call("podcast_episode", params);
+  },
+
+  /**
+   * Delete an existing podcast_episode
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID of podcast episode to delete
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#podcast_episode_delete}
+   */
+  podcastEpisodeDelete(params) {
+    return this.call("podcast_episode_delete", params);
+  },
+
+  /**
+   * Sync and download new podcast episodes
+   * ACCESS REQUIRED: 50 (Content Manager)
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID of podcast (required)
+   * @param {import("./base.js").UID} [params.id] Alias of filter (Ampache 7.9.0+)
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#update_podcast}
+   */
+  updatePodcast(params) {
+    return this.call("update_podcast", params);
+  },
+
+  /**
+   * This returns the episodes for a podcast that have been deleted
+   * @param {Object} [params]
+   * @param {number} [params.offset]
+   * @param {number} [params.limit]
+   * @returns {Promise<DeletedPodcastEpisodesResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#deleted_podcast_episodes}
+   */
+  deletedPodcastEpisodes(params) {
+    return this.call("deleted_podcast_episodes", params);
+  },
+};

package/src/preferences.js

@@ -0,0 +1,114 @@
+/**
+ * @typedef {Object} PreferenceResponse
+ * @property {import("./base.js").UID} id
+ * @property {string} name
+ * @property {string} level
+ * @property {string} description
+ * @property {string} value
+ * @property {string} type
+ * @property {string} category
+ * @property {string|null} subcategory
+ * @property {boolean} has_access
+ * @property {string} [values]
+ */
+
+/**
+ * @typedef {Object} PreferencesResponse
+ * @property {number} total_count
+ * @property {string} md5
+ * @property {PreferenceResponse[]} preference
+ */
+
+export const preferencesMethods = {
+  /**
+   * Get your server preferences
+   * ACCESS REQUIRED: 100 (Admin)
+   * @remarks MINIMUM_API_VERSION=5.0.0
+   * @returns {Promise<PreferencesResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#system_preferences}
+   */
+  systemPreferences() {
+    return this.call("system_preferences");
+  },
+
+  /**
+   * Get your system preference by name
+   * ACCESS REQUIRED: 100 (Admin)
+   * @remarks MINIMUM_API_VERSION=5.0.0
+   * @param {Object} params
+   * @param {string} params.filter Preference name e.g ('notify_email', 'ajax_load')
+   * @returns {Promise<PreferenceResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#system_preference}
+   */
+  systemPreference(params) {
+    return this.call("system_preference", params);
+  },
+
+  /**
+   * Get your user preferences
+   * @remarks MINIMUM_API_VERSION=5.0.0
+   * @returns {Promise<PreferencesResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#user_preferences}
+   */
+  userPreferences() {
+    return this.call("user_preferences");
+  },
+
+  /**
+   * Get your user preference by name
+   * @remarks MINIMUM_API_VERSION=5.0.0
+   * @param {Object} params
+   * @param {string} params.filter Preference name e.g ('notify_email', 'ajax_load')
+   * @returns {Promise<PreferenceResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#user_preference}
+   */
+  userPreference(params) {
+    return this.call("user_preference", params);
+  },
+
+  /**
+   * Add a new preference to your server
+   * ACCESS REQUIRED: 100 (Admin)
+   * @param {Object} params
+   * @param {string} params.filter Preference name e.g ('notify_email', 'ajax_load')
+   * @param {"boolean"|"integer"|"string"|"special"} params.type boolean, integer, string, special
+   * @param {string|number} params.default string or integer default value
+   * @param {"interface"|"internal"|"options"|"playlist"|"plugins"|"streaming"} params.category Category type
+   * @param {string} [params.description]
+   * @param {string} [params.subcategory]
+   * @param {number} [params.level] access level required to change the value (default 100)
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#preference_create}
+   */
+  preferenceCreate(params) {
+    return this.call("preference_create", params);
+  },
+
+  /**
+   * Edit a preference value and apply to all users if allowed
+   * ACCESS REQUIRED: 100 (Admin)
+   * @remarks MINIMUM_API_VERSION=5.0.0
+   * @param {Object} params
+   * @param {string} params.filter Preference name e.g ('notify_email', 'ajax_load')
+   * @param {string|number} params.value (string/integer) Preference value
+   * @param {import("./base.js").BinaryBoolean} [params.all] 0, 1 apply to all users
+   * @param {import("./base.js").BinaryBoolean} [params.default] 0, 1 set as system default (New and public users). ACCESS: 100 (Admin)
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#preference_edit}
+   */
+  preferenceEdit(params) {
+    return this.call("preference_edit", params);
+  },
+
+  /**
+   * Delete a non-system preference by name
+   * ACCESS REQUIRED: 100 (Admin)
+   * @param {Object} params
+   * @param {string} params.filter Preference name e.g ('notify_email', 'ajax_load')
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#preference_delete}
+   */
+  preferenceDelete(params) {
+    return this.call("preference_delete", params);
+  },
+};

package/src/shares.js

@@ -0,0 +1,99 @@
+/**
+ * @typedef {Object} ShareResponse
+ * @property {import("./base.js").UID} id
+ * @property {string} name
+ * @property {string} owner
+ * @property {boolean} allow_stream
+ * @property {boolean} allow_download
+ * @property {number} creation_date
+ * @property {number} lastvisit_date
+ * @property {string} object_type
+ * @property {import("./base.js").UID} object_id
+ * @property {number} expire_days
+ * @property {number} max_counter
+ * @property {number} counter
+ * @property {string} secret
+ * @property {string} public_url
+ * @property {string} description
+ */
+
+/**
+ * @typedef {Object} SharesResponse
+ * @property {number} total_count
+ * @property {string} md5
+ * @property {ShareResponse[]} share
+ */
+
+export const sharesMethods = {
+  /**
+   * This searches the shares and returns... shares
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} [params]
+   * @param {string} [params.filter] UID to find
+   * @param {import("./base.js").BinaryBoolean} [params.exact] 0, 1 boolean to match the exact filter string
+   * @param {number} [params.offset]
+   * @param {number} [params.limit]
+   * @param {string} [params.cond]
+   * @param {string} [params.sort]
+   * @returns {Promise<SharesResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#shares}
+   */
+  shares(params) {
+    return this.call("shares", params);
+  },
+
+  /**
+   * Return a share from UID
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID to find
+   * @returns {Promise<ShareResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#share}
+   */
+  share(params) {
+    return this.call("share", params);
+  },
+
+  /**
+   * Create a public url that can be used by anyone to stream media.
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID of object you are sharing
+   * @param {"song"|"album"|"artist"|"playlist"|"podcast"|"podcast_episode"|"video"} params.type
+   * @param {string} [params.description] description (will be filled for you if empty)
+   * @param {number} [params.expires] days to keep active
+   * @returns {Promise<ShareResponse>}
+   * @see {@link https://ampache.org/api/api-json-methods#share_create}
+   */
+  shareCreate(params) {
+    return this.call("share_create", params);
+  },
+
+  /**
+   * Update the description and/or expiration date for an existing share
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID to find
+   * @param {import("./base.js").BinaryBoolean} [params.stream] 0, 1
+   * @param {import("./base.js").BinaryBoolean} [params.download] 0, 1
+   * @param {number} [params.expires] days to keep active
+   * @param {string} [params.description] description
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#share_edit}
+   */
+  shareEdit(params) {
+    return this.call("share_edit", params);
+  },
+
+  /**
+   * Delete an existing share.
+   * @remarks MINIMUM_API_VERSION=420000
+   * @param {Object} params
+   * @param {import("./base.js").UID} params.filter UID of share to delete
+   * @returns {Promise<import("./base.js").Success>}
+   * @see {@link https://ampache.org/api/api-json-methods#share_delete}
+   */
+  shareDelete(params) {
+    return this.call("share_delete", params);
+  },
+};

package/src/shouts.js

@@ -0,0 +1,24 @@
+/**
+ * @typedef {Object} ShoutResponse
+ * @property {import("./base.js").UID} id
+ * @property {number} date
+ * @property {string} text
+ * @property {import("./users.js").UserSummary} user
+ * @property {"song"|"album"|"artist"|"playlist"} object_type
+ * @property {import("./base.js").UID} object_id
+ */
+
+export const shoutsMethods = {
+  /**
+   * This gets the latest posted shouts
+   * @remarks MINIMUM_API_VERSION=380001
+   * @param {Object} [params]
+   * @param {string} [params.username] Username to find
+   * @param {number} [params.limit] Maximum number of results to return
+   * @returns {Promise<{ shout: ShoutResponse[] }>}
+   * @see {@link https://ampache.org/api/api-json-methods#last_shouts}
+   */
+  last_shouts(params) {
+    return this.call("last_shouts", params);
+  },
+};