<commit_before>/**
 * This file contains the readily availbile functions which interact with the
 * ITSLanguage categories API.
 */

import {authorisedRequest} from './communication';

// The URL for the category handler(s).
const url = '/categories';


/**
 * Create a new category.
 *
 * @param {Object} category - The category to create.
 *
 * @returns {Promise} - The category creation promise.
 */
export function create(category) {
  return authorisedRequest('POST', url, category);
}


/**
 * Get a single category by its ID.
 *
 * @param {string} id - The ID of the desired category.
 *
 * @returns {Promise} - The promise for the category.
 */
export function getById(id) {
  return authorisedRequest('GET', `${url}/${id}`);
}


/**
 * Get a all categories.
 *
 * By default all categories are fetched though it is allowed to pass filters.
 * as a `URLSearchParams` object.
 *
 * @param {URLSearchParams} [filters] - The filters to apply to the category
 *                                      list.
 *
 * @throws {Promise.<string>} - If the given optional filters are not an<commit_msg>docs: improve documentation on category API<commit_after>/**
 * This file contains the readily availbile functions which interact with the
 * ITSLanguage categories API.
 */

import {authorisedRequest} from './communication';

// The URL for the category handler(s).
const url = '/categories';


/**
 * Create a new category.
 *
 * The most convenient way to pas a category to this create function is to make use of the FormData object.
 *
 * @param {Object} category - The category to create.
 * @param {string} [category.id] - The category identifier. If none is given, one is generated.
 * @param {string} [category.parent] - Identifier of the parent category.
 * @param {string} [category.name] - A name for the category.
 * @param {string} [category.description] - A possible more verbose description about the category.
 * @param {string} [category.color] - A color, preferably in RGB format.
 * @param {blob} [category.image] - An image to show with the category.
 * @param {blob} [category.icon] - An icon to show with the category.
 * @param {string} [category.speechChallenges] - Speech Challenge identifiers categorized in the category.
 *
 * @returns {Promise} - The category creation promise.
 */
export function create(category) {
  return authorisedRequest('POST', url, category);
}


/**
 * Get a single category by its ID.
 *
 * @param {string} id - The ID of the desired category.
 *
 * @returns {Promise} - The promise for the category.
 */
export function getById(id) {
  return authorisedRequest('GET', `${url}/${id}`);
}


/**
 * Get a all categories.
 *
 * By default all categories are fetched though it is allowed to pass filters.
 * as a `URLSearchParams` object.
 *
 * @param {URLSearchParams} [filters] - The filters to apply to the category
 *                                      list.
 *
 * @throws {Promise.<string>} - If the given optional filters are not an
{'fraction_non_alphanumeric': 0.11416136591898225, 'fraction_numerical': 0.0, 'mean_word_length': 3.324167872648336, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4473489', 'n_tokens_mistral': 819, 'n_tokens_neox': 804, 'n_words': 349}