@itslanguage/api

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>communication/index.js - ITSLanguage JavaScript SDK</title> <meta name="description" content="Speech technology for language education. JSDoc 3 website for the JavaScript SDK." /> <meta name="keywords" content="itslangauge, jsdoc, documentation, speech, speech technology" /> <meta name="keyword" content="itslangauge, jsdoc, documentation, speech, speech technology" /> <meta property="og:title" content="ITSLanguage JavaScript SDK"/> <meta property="og:type" content="website"/> <meta property="og:image" content="https://avatars0.githubusercontent.com/u/20972344?s=400&u=73936e7fa2d2a1e5c180a11675bf9166d3717a6d&v=4"/> <meta property="og:site_name" content="ITSLanguage JavaScript SDK"/> <meta property="og:url" content="http://itslanguage.github.io/itslanguage-js/"/> <script src="scripts/prettify/prettify.js"></script> <script src="scripts/prettify/lang-css.js"></script>  <link type="text/css" rel="stylesheet" href="styles/prettify.css"> <link type="text/css" rel="stylesheet" href="styles/jsdoc.css"> <script src="scripts/nav.js" defer></script> <meta name="viewport" content="width=device-width, initial-scale=1.0"> </head> <body> <input type="checkbox" id="nav-trigger" class="nav-trigger" /> <label for="nav-trigger" class="navicon-button x"> <div class="navicon"></div> </label> <label for="nav-trigger" class="overlay"></label> <nav > <input type="text" id="nav-search" placeholder="Search" /> <h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/itslanguage/itslanguage-js" target="_blank" class="menu-item" id="repository" >Github repo</a></h2><h3>Modules</h3><ul><li><a href="module-api.html">api</a><ul class='members'><li data-type='member'><a href="module-api.html#.version">version</a></li></ul><ul class='methods'><li data-type='method'><a href="module-api.html#.createItslApi">createItslApi</a></li></ul></li><li><a href="module-api_authentication.html">api/authentication</a><ul class='methods'><li data-type='method'><a href="module-api_authentication.html#.assembleScope">assembleScope</a></li><li data-type='method'><a href="module-api_authentication.html#.authenticate">authenticate</a></li><li data-type='method'><a href="module-api_authentication.html#.impersonate">impersonate</a></li></ul></li><li><a href="module-api_basicauth.html">api/basicauth</a><ul class='methods'><li data-type='method'><a href="module-api_basicauth.html#.create">create</a></li></ul></li><li><a href="module-api_broadcaster.html">api/broadcaster</a></li><li><a href="module-api_categories.html">api/categories</a><ul class='methods'><li data-type='method'><a href="module-api_categories.html#.create">create</a></li><li data-type='method'><a href="module-api_categories.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_categories.html#.getAllWithParentId">getAllWithParentId</a></li><li data-type='method'><a href="module-api_categories.html#.getById">getById</a></li><li data-type='method'><a href="module-api_categories.html#.update">update</a></li></ul></li><li><a href="module-api_challenges.html">api/challenges</a><ul class='members'><li data-type='member'><a href="module-api_challenges.html#.choice">choice</a></li><li data-type='member'><a href="module-api_challenges.html#.choiceRecognition">choiceRecognition</a></li><li data-type='member'><a href="module-api_challenges.html#.feedback">feedback</a></li><li data-type='member'><a href="module-api_challenges.html#.feedbackSpeech">feedbackSpeech</a></li><li data-type='member'><a href="module-api_challenges.html#.pronunciation">pronunciation</a></li><li data-type='member'><a href="module-api_challenges.html#.pronunciationAnalysis">pronunciationAnalysis</a></li><li data-type='member'><a href="module-api_challenges.html#.speech">speech</a></li><li data-type='member'><a href="module-api_challenges.html#.speechRecording">speechRecording</a></li></ul></li><li><a href="module-api_challenges_choice.html">api/challenges/choice</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_choice.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_choice.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_choice.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_choice_recognition.html">api/challenges/choice/recognition</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.getById">getById</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.prepare">prepare</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.prepareChallenge">prepareChallenge</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.recognise">recognise</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.recogniseAudioStream">recogniseAudioStream</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#.recogniseNonStreaming">recogniseNonStreaming</a></li><li data-type='method'><a href="module-api_challenges_choice_recognition.html#~url">url</a></li></ul></li><li><a href="module-api_challenges_feedback.html">api/challenges/feedback</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_feedback.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_feedback.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_feedback.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_feedback_speech.html">api/challenges/feedback/speech</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.feedback">feedback</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.listenAndReply">listenAndReply</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.pause">pause</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.prepare">prepare</a></li><li data-type='method'><a href="module-api_challenges_feedback_speech.html#.resume">resume</a></li></ul></li><li><a href="module-api_challenges_pronunciation.html">api/challenges/pronunciation</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_pronunciation.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_pronunciation.html#.deleteChallenge">deleteChallenge</a></li><li data-type='method'><a href="module-api_challenges_pronunciation.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_pronunciation.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_pronunciation_analysis.html">api/challenges/pronunciation/analysis</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.alignChallenge">alignChallenge</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.endStreamAudio">endStreamAudio</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.getById">getById</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.prepare">prepare</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.prepareAudio">prepareAudio</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.prepareChallenge">prepareChallenge</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#.streamAudio">streamAudio</a></li><li data-type='method'><a href="module-api_challenges_pronunciation_analysis.html#~url">url</a></li></ul></li><li><a href="module-api_challenges_speech.html">api/challenges/speech</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_speech.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_speech.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_speech.html#.getById">getById</a></li></ul></li><li><a href="module-api_challenges_speech_recordings.html">api/challenges/speech/recordings</a><ul class='methods'><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.create">create</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.getById">getById</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#.record">record</a></li><li data-type='method'><a href="module-api_challenges_speech_recordings.html#~url">url</a></li></ul></li><li><a href="module-api_communication.html">api/communication</a><ul class='members'><li data-type='member'><a href="module-api_communication.html#.settings">settings</a></li><li data-type='member'><a href="module-api_communication.html#~APPLICATION_JSON">APPLICATION_JSON</a></li><li data-type='member'><a href="module-api_communication.html#~AUTHORIZATION">AUTHORIZATION</a></li><li data-type='member'><a href="module-api_communication.html#~CONTENT_TYPE">CONTENT_TYPE</a></li><li data-type='member'><a href="module-api_communication.html#~LINK">LINK</a></li></ul><ul class='methods'><li data-type='method'><a href="module-api_communication.html#.addAccessToken">addAccessToken</a></li><li data-type='method'><a href="module-api_communication.html#.authorisedRequest">authorisedRequest</a></li><li data-type='method'><a href="module-api_communication.html#.request">request</a></li><li data-type='method'><a href="module-api_communication.html#.updateSettings">updateSettings</a></li><li data-type='method'><a href="module-api_communication.html#~getBearerToken">getBearerToken</a></li><li data-type='method'><a href="module-api_communication.html#~handleResponse">handleResponse</a></li></ul></li><li><a href="module-api_communication_websocket.html">api/communication/websocket</a><ul class='methods'><li data-type='method'><a href="module-api_communication_websocket.html#.closeWebsocketConnection">closeWebsocketConnection</a></li><li data-type='method'><a href="module-api_communication_websocket.html#.getWebsocketConnection">getWebsocketConnection</a></li><li data-type='method'><a href="module-api_communication_websocket.html#.makeWebsocketCall">makeWebsocketCall</a></li><li data-type='method'><a href="module-api_communication_websocket.html#.openWebsocketConnection">openWebsocketConnection</a></li><li data-type='method'><a href="module-api_communication_websocket.html#~establishNewBundesbahn">establishNewBundesbahn</a></li><li data-type='method'><a href="module-api_communication_websocket.html#~handleWebsocketAuthorisationChallenge">handleWebsocketAuthorisationChallenge</a></li></ul></li><li><a href="module-api_emailauth.html">api/emailauth</a><ul class='methods'><li data-type='method'><a href="module-api_emailauth.html#.create">create</a></li><li data-type='method'><a href="module-api_emailauth.html#~url">url</a></li></ul></li><li><a href="module-api_groups.html">api/groups</a><ul class='methods'><li data-type='method'><a href="module-api_groups.html#.create">create</a></li><li data-type='method'><a href="module-api_groups.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_groups.html#.getById">getById</a></li></ul></li><li><a href="module-api_organisations.html">api/organisations</a><ul class='methods'><li data-type='method'><a href="module-api_organisations.html#.create">create</a></li><li data-type='method'><a href="module-api_organisations.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_organisations.html#.getById">getById</a></li></ul></li><li><a href="module-api_profile.html">api/profile</a><ul class='methods'><li data-type='method'><a href="module-api_profile.html#.create">create</a></li><li data-type='method'><a href="module-api_profile.html#.getById">getById</a></li><li data-type='method'><a href="module-api_profile.html#.getCurrent">getCurrent</a></li><li data-type='method'><a href="module-api_profile.html#~url">url</a></li></ul></li><li><a href="module-api_progress.html">api/progress</a><ul class='methods'><li data-type='method'><a href="module-api_progress.html#.getById">getById</a></li></ul></li><li><a href="module-api_roles.html">api/roles</a><ul class='methods'><li data-type='method'><a href="module-api_roles.html#.create">create</a></li><li data-type='method'><a href="module-api_roles.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_roles.html#.getById">getById</a></li></ul></li><li><a href="module-api_tenants.html">api/tenants</a><ul class='methods'><li data-type='method'><a href="module-api_tenants.html#.create">create</a></li><li data-type='method'><a href="module-api_tenants.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_tenants.html#.getById">getById</a></li></ul></li><li><a href="module-api_users.html">api/users</a><ul class='methods'><li data-type='method'><a href="module-api_users.html#.create">create</a></li><li data-type='method'><a href="module-api_users.html#.getAll">getAll</a></li><li data-type='method'><a href="module-api_users.html#.getById">getById</a></li><li data-type='method'><a href="module-api_users.html#.getCurrent">getCurrent</a></li></ul></li><li><a href="module-api_utils.html">api/utils</a><ul class='methods'><li data-type='method'><a href="module-api_utils.html#.asyncBlobToArrayBuffer">asyncBlobToArrayBuffer</a></li><li data-type='method'><a href="module-api_utils.html#.checkAudioIsNotEmpty">checkAudioIsNotEmpty</a></li><li data-type='method'><a href="module-api_utils.html#.dataToBase64">dataToBase64</a></li></ul></li><li><a href="module-api_utils_audio-over-socket.html">api/utils/audio-over-socket</a><ul class='methods'><li data-type='method'><a href="module-api_utils_audio-over-socket.html#.encodeAndSendAudioOnDataAvailable">encodeAndSendAudioOnDataAvailable</a></li><li data-type='method'><a href="module-api_utils_audio-over-socket.html#.prepareServerForAudio">prepareServerForAudio</a></li><li data-type='method'><a href="module-api_utils_audio-over-socket.html#.registerStreamForRecorder">registerStreamForRecorder</a></li></ul></li></ul><h3>Classes</h3><ul><li><a href="module-api.Itslanguage.html">Itslanguage</a></li></ul><h3>Events</h3><ul><li><a href="broadcaster.html#event:websocketserverreadyforaudio">websocketserverreadyforaudio</a></li></ul> </nav> <div id="main"> <h1 class="page-title">communication/index.js</h1> <section> <article> <pre class="prettyprint source linenums"><code>/** * This file contains the settings and the communication mechanism for the ITSLanguage REST API. * * @module api/communication */ /** * Content-Type HTTP Header key. * @type {string} */ const CONTENT_TYPE = 'Content-Type'; /** * Authorization HTTP Header key. * @type {string} */ const AUTHORIZATION = 'Authorization'; /** * Content-Type HTTP Header value. * @type {string} */ const APPLICATION_JSON = 'application/json'; /** * Link header value. * @type {string} */ const LINK = 'link'; /** * The settings to use for the communication with the ITSLanguage API. */ export const settings = { apiUrl: 'https://api.itslanguage.nl', wsUrl: null, authorizationToken: null, }; /** * Update the settings with the `newSettings`. * * @param {Object} newSettings - The settings to inject/update. * * @throws {Error} - When the given `newSettings` is something other than a object. */ export function updateSettings(newSettings) { if (!newSettings || !(newSettings instanceof Object)) { throw new Error('Please, only provide objects as settings.'); } Object.assign(settings, newSettings); } function parseLinkHeader(linkHeader) { const links = linkHeader.split(','); return links.reduce((acc, link) => { let [url, rel] = link.split(';'); url = url.replace(/<(.*)>/, '$1').trim(); rel = rel.replace(/rel="(.*)"/, '$1').trim(); acc[rel] = { url, }; return acc; }, {}); } /** * Parse the response of a fetch request. * * Try to parse the given response body as JSON, if it isn't Leave the response as is. * * @param {Response} response - The response to parse. * * @throws {Promise<string>} - When the request wasn't okay and the contents of the response isn't * json. * @throws {Promise<Error>} - When the request wasn't okay and the contents of the response is json. * * @returns {Promise|Response} - The contents of a JSON response or the response itself if the body * is something other than JSON. */ function handleResponse(response) { const responseContentType = response.headers.get(CONTENT_TYPE); const responseLink = response.headers.get(LINK); let parsedLinkHeader = {}; if (responseLink) { parsedLinkHeader = parseLinkHeader(responseLink); } // The ITSLanguage API should return JSON. If t if (responseContentType && responseContentType.includes(APPLICATION_JSON)) { return response.json().then(json => { if (response.ok) { if (responseLink) { return { data: json, ...parsedLinkHeader, }; } return json; } return Promise.reject(json); }); } if (!response.ok) { return Promise.reject( new Error(`${response.status}: ${response.statusText}`), ); } return response; } /** * Perform an HTTP request for the given method, url, body, and headers. * * In case the given url is a partial url, meaning it starts with a `/`, the base URL to the * ITSLanguage API is prepended. * * When a Object instance is provided as body, it'll be transformed into JSON. Unless it is either a * `URLSearchParams` or a `FormData` object. Anything else is sent as plain text. * * @param {string} method - The request METHOD ('GET', 'POST', 'PUT', 'DELETE'). * @param {string} url - The location to send the request to. * @param {*} [body] - Anything which needs to be sent somewhere. * @param {Headers} [headers] - Extra headers to send with the request. * * @returns {Promise<Object>} The response of the made request. */ export function request(method, url, body, headers) { const requestHeaders = headers || new Headers(); let requestBody = body; // In case of (any) object-type if ( !(body instanceof URLSearchParams || body instanceof FormData) && body instanceof Object ) { requestHeaders.set('Content-Type', 'application/json'); requestBody = JSON.stringify(body); } // In case of URLSearchParams if (body instanceof URLSearchParams) { requestHeaders.set('Content-Type', 'application/x-www-form-urlencoded'); requestBody = body.toString(); } // Prepend the url with the set url or use it complete when there was no url set. let requestURL = url; if (url.startsWith('/') || !url) { requestURL = `${settings.apiUrl}${url}`; } // Gather all the options const requestOptions = { method, headers: requestHeaders, body: requestBody, }; // Use fetch to send the request out! return fetch(requestURL, requestOptions).then(handleResponse); } /** * Build a bearer token from the `authorizationToken` in the settings object. * * @throws {Error} When no authorizationToken is set. * * @returns {string} The generated bearer token. */ function getBearerToken() { if (!settings.authorizationToken) { throw new Error('Please authenticate first.'); } return `Bearer ${settings.authorizationToken}`; } /** * Add an access token to a given URL. * * @param {string} [url=''] - The URL to add an access token to. * @returns {string} An url with the access token appended. */ export function addAccessToken(url = '') { if (!settings.authorizationToken) { return url; } return `${url}${ url.includes('?') ? '&' : '?' }access_token=${encodeURIComponent(settings.authorizationToken)}`; } /** * Perform an HTTP request with the desired method, body, and headers to the given partial * ITSLanguage API URL. * * This request will add the ``Authorization`` header to the request. * * This function only allows to make calls to the ITSLanguage API. * * @param {string} method - The request METHOD ('GET', 'POST', 'PUT', 'DELETE'). * @param {string} url - The location to send the request to. * @param {*} [body] - Anything which needs to be sent somewhere. * @param {Headers} [headers] - Extra headers to send with the request. * * @throws {Promise<string>} - When the given `url` param is not a partial URL, or when there is no * authorisation token available. * * @returns {Promise<Object>} - The response from the ITSLanguage API. */ export function authorisedRequest(method, url, body, headers) { // XXX remove the URL truthy check when all parts of the SDK no longer build // a complete url by themselves using the "private" settings object of their // connection reference. if (url && !url.startsWith('/') && !url.startsWith(settings.apiUrl)) { return Promise.reject( new Error('Only relative ITSLanguage API URLs are allowed.'), ); } try { const requestHeaders = headers || new Headers(); requestHeaders.set(AUTHORIZATION, getBearerToken()); return request(method, url, body, requestHeaders); } catch (unauthorised) { return Promise.reject(new Error(unauthorised.message)); } } </code></pre> </article> </section> </div> <br class="clear"> <footer> Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.3</a> on Mon Oct 12 2020 12:26:34 GMT+0000 (Coordinated Universal Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme. </footer> <script>prettyPrint();</script> <script src="scripts/polyfill.js"></script> <script src="scripts/linenumber.js"></script> <script src="scripts/search.js" defer></script> </body> </html>