Function

A promise which will resolve if the authentication concluded successfully, it'll reject in any other case. It resolves with the response body of the token request.

public authorisedRequest(method: string, url: string, body: *, headers: Headers): Promise<Object> source

import {authorisedRequest} from 'itslanguage/api/communication/index.js'

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.

Params:

Name	Type	Attribute	Description
method	string		The request METHOD ('GET', 'POST', 'PUT', 'DELETE').
url	string		The location to send the request to.
body	*	optional	Anything which needs to be sent somewhere.
headers	Headers	optional	Extra headers to send with the request.

Return:

The response from the ITSLanguage API.

Throw:

Promise.<string>

When the given url param is not a partial URL, or when there is no authorisation token availible.

public closeWebsocketConnection(): Promise<string> source

import {closeWebsocketConnection} from 'itslanguage/api/communication/websocket.js'

Close the current websocket connection.

Return:

Promise<string>

A promise which will resolve as soon as the connection was successfully closed.

public createCategory(category: Object): Promise source

import {createCategory} from 'itslanguage/api/categories.js'

Create a new category.

Params:

Name	Type	Attribute	Description
category	Object		The category to create.

Return:

The category creation promise.

public createChoiceChallenge(challenge: Object): Promise source

import {createChoiceChallenge} from 'itslanguage/api/challenges/choice/index.js'

Create a new choice challenge.

Params:

Name	Type	Attribute	Description
challenge	Object		The challenge to create.

Return:

The challenge creation promise.

public createChoiceRecognition(challengeId: string, audio: Blob, recognised: string, recognitionId: string): Promise source

import {createChoiceRecognition} from 'itslanguage/api/challenges/choice/recognition.js'

Submit an audio fragment for recognition. The recognition is created for the current authenticated user.

Params:

Name	Type	Attribute	Description
challengeId	string		The ID of the challenge to relate the recognition to.
audio	Blob		The actual audio.
recognised	string		The recognised string.
recognitionId	string	optional default: null	Unique identifier for the recognition. If none is given, one is generated.

Return:

The created recognition with an url to download the audio if needed.

See:

https://itslanguage.github.io/itslanguage-docs/api/recognitions/index.html#create-a-choice-recognition

public createGroup(group: Object): Promise source

import {createGroup} from 'itslanguage/api/groups.js'

Create a new group.

Params:

Name	Type	Attribute	Description
group	Object		The group to create.

Return:

The group creation promise.

public createOrganisation(organisation: Object): Promise source

import {createOrganisation} from 'itslanguage/api/organisations.js'

Create a new organisation.

Params:

Name	Type	Attribute	Description
organisation	Object		The organisation to create.

Return:

The organisation creation promise.

public createPronunciationChallenge(challenge: Object): Promise source

import {createPronunciationChallenge} from 'itslanguage/api/challenges/pronunciation/index.js'

Create a new pronunciation challenge.

Params:

Name	Type	Attribute	Description
challenge	Object		The pronunciation challenge to create.

Return:

The pronunciation challenge creation promise.

public createSpeechChallenge(challenge: Object): Promise source

import {createSpeechChallenge} from 'itslanguage/api/challenges/speech/index.js'

Create a new speech challenge.

Params:

Name	Type	Attribute	Description
challenge	Object		The challenge to create.

Return:

The challenge creation promise.

public createSpeechRecording(challenge: string, recorder: MediaRecorder): Promise source

import {createSpeechRecording} from 'itslanguage/api/challenges/speech/recordings.js'

Create a new recording for the given challenge with the data from the given recorder.

Params:

Name	Type	Attribute	Description
challenge	string		The ID of the challenge for which a recording is made.
recorder	MediaRecorder		The recorder to use to get the recording.

Return:

The promise which resolves once the speech recording has successfully been stored.

Emit:

websocketserverreadyforaudio

When the websocket server has been prepared for and is ready to receive the audio.

public createUser(user: Object): Promise source

import {createUser} from 'itslanguage/api/users.js'

Create a new user.

Params:

Name	Type	Attribute	Description
user	Object		The user to create.

Return:

The user creation promise.

public dataToBase64(data: ArrayBuffer): string source

import {dataToBase64} from 'itslanguage/api/utils/index.js'

Convert the given ArrayBuffer to a base64 encoded string.

Params:

Name	Type	Attribute	Description
data	ArrayBuffer		The data to transform to base64.

Return:

string

The base64 encoded data.

public deletePronunciationChallenge(id: string): Promise source

import {deletePronunciationChallenge} from 'itslanguage/api/challenges/pronunciation/index.js'

Delete the pronunciation challenge with the given ID.

Params:

Name	Type	Attribute	Description
id	string		The ID of the pronunciation challeng to delete.

Return:

The pronunciation delete promise.

public encodeAndSendAudioOnDataAvailible(id: string, recorder: MediaRecorder | Recorder, rpc: string): Promise<*> source

import {encodeAndSendAudioOnDataAvailible} from 'itslanguage/api/utils/audio-over-socket.js'

Encode the audio as base64 and send it to the websocket server.

Params:

Name	Type	Attribute	Description
id	string		The reserved ID for the audio.
recorder	MediaRecorder \| Recorder		The recorder to use to get the recording.
rpc	string		The RPC to use to store the data.

Return:

The response of the given RPC.

public endStreamAudioForPronunciationAnalysis(analyseId: string, progressCb: Function): Promise<*> source

import {endStreamAudioForPronunciationAnalysis} from 'itslanguage/api/challenges/pronunciation/analysis.js'

Finishing the recording means we're ready to analyse! Smartest man in the entire universe. We also accept a special callback that can be used to receive progress on.

Params:

Name	Type	Attribute	Description
analyseId	string		The ID of the Analysis to analyse on.
progressCb	Function	optional	A callback which will be used to receive progress on.

Return:

The result will return the analysis.

public generateWaveSample(duration: number): string source

import {generateWaveSample} from 'itslanguage/audio/audio-tools.js'

Generate a dummy Wave file for testing purposes.

Params:

Name	Type	Attribute	Description
duration	number		Length of audio in seconds.

Return:

string

A new URL containing the Wave file.

public getAllCategories(filters: URLSearchParams): Promise source

import {getAllCategories} from 'itslanguage/api/categories.js'

Get a all categories.

By default all categories are fetched though it is allowed to pass filters. as a URLSearchParams object.

Params:

Name	Type	Attribute	Description
filters	URLSearchParams	optional	The filters to apply to the category list.

Return:

The promise for the categories.

Throw:

Promise.<string>

If the given optional filters are not an instance of URLSearchParams.

public getAllChoiceChallenges(filters: URLSearchParams): Promise source

import {getAllChoiceChallenges} from 'itslanguage/api/challenges/choice/index.js'

Get a all choice challenges.

By default all choice challenges are fetched though it is allowed to pass filters as a URLSearchParams object.

Params:

Name	Type	Attribute	Description
filters	URLSearchParams	optional	The filters to apply to the category list.

Return:

The promise for the choice challenges.

Throw:

Promise.<string>

If the given optional filters are not an instance of URLSearchParams.

public getAllChoiceRecognitions(challengeId: string): Promise source

import {getAllChoiceRecognitions} from 'itslanguage/api/challenges/choice/recognition.js'

Get all Choice Recognitions for a specific Choice Challenge.

Params:

Name	Type	Attribute	Description
challengeId	string		ID of the Choice Challenge to get all the recognitions for.

Return:

Promise with the Choice Recognitions as result if successful.

See:

https://itslanguage.github.io/itslanguage-docs/api/recognitions/index.html#list-choice-recognitions

public getAllGroups(filters: URLSearchParams): Promise source

import {getAllGroups} from 'itslanguage/api/groups.js'

Get a all groups.

By default all groups are fetched though it is allowed to pass filters as a URLSearchParams object.

Params:

Name	Type	Attribute	Description
filters	URLSearchParams	optional	The filters to apply to the category list.

Return:

The promise for the groups.

Throw:

Promise.<string>

If the given optional filters are not an instance of URLSearchParams.

public getAllOrganisations(filters: URLSearchParams): Promise source

import {getAllOrganisations} from 'itslanguage/api/organisations.js'

Get a all organisations.

By default all organisations are fetched though it is allowed to pass filters as a URLSearchParams object.

Params:

Name	Type	Attribute	Description
filters	URLSearchParams	optional	The filters to apply to the category list.

Return:

The promise for the organisations.

Throw:

Promise.<string>

If the given optional filters are not an instance of URLSearchParams.

public getAllPronunciationChallenges(filters: URLSearchParams): Promise source

import {getAllPronunciationChallenges} from 'itslanguage/api/challenges/pronunciation/index.js'

Get a all pronunciation challenges.

By default all pronunciation challenges are fetched though it is allowed to pass filters as a URLSearchParams object.

Params:

Name	Type	Attribute	Description
filters	URLSearchParams	optional	The filters to apply to the category list.

Return:

The promise for the pronunciation challenges.

Throw:

Promise.<string>

If the given optional filters are not an instance of URLSearchParams.

public getAllRoles(filters: URLSearchParams): Promise source

import {getAllRoles} from 'itslanguage/api/roles.js'

Get a all roles.

By default all roles are fetched though it is allowed to pass filters as a URLSearchParams object.

Params:

Name	Type	Attribute	Description
filters	URLSearchParams	optional	The filters to apply to the category list.

Return:

The promise for the roles.

Throw:

Promise.<string>

If the given optional filters are not an instance of URLSearchParams.

public getAllSpeechChallenges(filters: URLSearchParams): Promise source

import {getAllSpeechChallenges} from 'itslanguage/api/challenges/speech/index.js'

Get a all speech challenges.

By default all speech challenges are fetched though it is allowed to pass filters as a URLSearchParams object.

Params:

Name	Type	Attribute	Description
filters	URLSearchParams	optional	The filters to apply to the category list.

Return:

The promise for the speech challenges.

Throw:

Promise.<string>

If the given optional filters are not an instance of URLSearchParams.

public getAllSpeechRecordings(challenge: string, filters: URLSearchParams): Promise source

import {getAllSpeechRecordings} from 'itslanguage/api/challenges/speech/recordings.js'

Get a all speech recordings.

By default all speech recordings are fetched though it is allowed to pass filters as a URLSearchParams object.

Params:

Name	Type	Attribute	Description
challenge	string		The ID of the challenge for which the recording was made.
filters	URLSearchParams	optional	The filters to apply to the category list.

Return:

The promise for the speech recordings.

Throw:

Promise.<string>

If the given optional filters are not an instance of URLSearchParams.

public getAllUsers(filters: URLSearchParams): Promise source

import {getAllUsers} from 'itslanguage/api/users.js'

Get a all users.

By default all users are fetched though it is allowed to pass filters as a URLSearchParams object.

Params:

Name	Type	Attribute	Description
filters	URLSearchParams	optional	The filters to apply to the category list.

Return:

The promise for the users.

Throw:

Promise.<string>

If the given optional filters are not an instance of URLSearchParams.

public getCategoryByID(id: string): Promise source

import {getCategoryByID} from 'itslanguage/api/categories.js'

Get a single category by its ID.

Params:

Name	Type	Attribute	Description
id	string		The ID of the desired category.

Return:

The promise for the category.

public getChoiceChallengeByID(id: string): Promise source

import {getChoiceChallengeByID} from 'itslanguage/api/challenges/choice/index.js'

Get a single choice challenge by its ID.

Params:

Name	Type	Attribute	Description
id	string		The ID of the desired choice challenge.

Return:

The promise for the choice challenge.

public getChoiceRecognitionByID(challengeId: string, id: string): Promise source

import {getChoiceRecognitionByID} from 'itslanguage/api/challenges/choice/recognition.js'

Get a single ChoiceRecognition by its ID.

Params:

Name	Type	Attribute	Description
challengeId	string		ID of the Choice Challenge to get all the recognitions for.
id	string		ID of the choice recognition to get.

Return:

Promise with the Choice Recognition as result if successful.

See:

https://itslanguage.github.io/itslanguage-docs/api/recognitions/index.html#get-a-single-choice-recognition

public getGroupByID(id: string): Promise source

import {getGroupByID} from 'itslanguage/api/groups.js'

Get a single group by its ID.

Params:

Name	Type	Attribute	Description
id	string		The ID of the desired group.

Return:

The promise for the group.

public getOrganisationByID(id: string): Promise source

import {getOrganisationByID} from 'itslanguage/api/organisations.js'

Get a single organisation by its ID.

Params:

Name	Type	Attribute	Description
id	string		The ID of the desired organisation.

Return:

The promise for the organisation.

public getPronunciationAnalysisById(challengeId: string, analysisId: string): Promise<Object> source

import {getPronunciationAnalysisById} from 'itslanguage/api/challenges/pronunciation/analysis.js'

Ask the backend for a Pronunciation Analysis.

Params:

Name	Type	Attribute	Description
challengeId	string		The ID of the corresponding challenge.
analysisId	string		The ID of the analysis you want result for.

Return:

The Pronunciation Analysis.

public getPronunciationChallengeByID(id: string): Promise source

import {getPronunciationChallengeByID} from 'itslanguage/api/challenges/pronunciation/index.js'

Get a single pronunciation challenge by its ID.

Params:

Name	Type	Attribute	Description
id	string		The ID of the desired pronunciation challenge.

Return:

The promise for the pronunciation challenge.

public getRoleByID(id: string): Promise source

import {getRoleByID} from 'itslanguage/api/roles.js'

Get a single role by its ID.

Params:

Name	Type	Attribute	Description
id	string		The ID of the desired role.

Return:

The promise for the role.

public getSpeechChallengeByID(id: string): Promise source

import {getSpeechChallengeByID} from 'itslanguage/api/challenges/speech/index.js'

Get a single speech challenge by its ID.

Params:

Name	Type	Attribute	Description
id	string		The ID of the desired speech challenge.

Return:

The promise for the speech challenge.

public getSpeechRecordingByID(challenge: string, id: string): Promise source

import {getSpeechRecordingByID} from 'itslanguage/api/challenges/speech/recordings.js'

Get a single speech recording by its ID.

Params:

Name	Type	Attribute	Description
challenge	string		The ID of the challenge for which the recording was made.
id	string		The ID of the desired speech recording.

Return:

The promise for the speech recording.

public getUserByID(id: string): Promise source

import {getUserByID} from 'itslanguage/api/users.js'

Get a single user by its ID.

Params:

Name	Type	Attribute	Description
id	string		The ID of the desired user.

Return:

@see: https://itslanguage.github.io/itslanguage-docs/api/oauth2/index.html#impersonation

The promise for the user.

public impersonate(scope: string): Promise source

import {impersonate} from 'itslanguage/api/auth.js'

Impersonate some other tenant, user or organisation. The impersonation will be done by using the authorisation token for the current user.

On a successful impersonation, the settings are updated so every follow-up API requests is authorized by the access_token required with this impersonation.

As an admin or tenant user it is possible to do impersonation. This goes from top to down. So, a tenant user can impersonate an organisation, or an user in an organisation. But an user can't impersonate.

Params:

Name	Type	Attribute	Description
scope	string	optional	The scope of the impersonation. Omitting this value will cause the API to return a token for the current user.

Return:

A promise which will resolve if the authentication concluded successfully, it'll reject in any other case. It resolves with the response body of the token request.

public makeWebsocketCall(rpc: string, options: Object): Promise<*> source

import {makeWebsocketCall} from 'itslanguage/api/communication/websocket.js'

Make a rpc call to the ITSLanguage websocket server.

This method will try to establish a websocket connection if there isn't one already.

Params:

Name	Type	Attribute	Description
rpc	string		The RPC to make. This be prepended by `nl.itslanguage` as the websocket server only handles websocket calls when the RPC starts with that prefix.
options	Object	optional	Destructured object with options to pass to the websocket server.
options.args	Array	optional	An array with arguments to pass to the RPC.
options.kwargs	Object	optional	An object (dictionary) with arguments to pass to the RPC.
options.options	Object	optional	The options to pass to the RPC.
options.progressCb	Function	optional	Optional callback to receive progressed results.

Return:

The response of the websocket call.

public openWebsocketConnection(): Promise<string> source

import {openWebsocketConnection} from 'itslanguage/api/communication/websocket.js'

Open a new websocket connection.

There there currently is a open connection, close it and open a new connection.

Return:

Promise<string>

A resolved promise which resolves when the connection was successfully created and opened.

public performAlignmentOnChallenge(analysisId: string): Promise<*> source

import {performAlignmentOnChallenge} from 'itslanguage/api/challenges/pronunciation/analysis.js'

A Pronunciaion Challange could hold an alignment allready. If not so this function will instruct the backend to create the alignment and return it to the client.

Params:

Name	Type	Attribute	Description
analysisId	string		The ID of the analysis to create the alignment for.

Return:

The alignment.

public performChoiceRecognition(challengeId: string, recorder: Recorder, progressCb: Function): Promise source

import {performChoiceRecognition} from 'itslanguage/api/challenges/choice/recognition.js'

Expose easy way to run the choice challenge in one go.

Params:

Name	Type	Attribute	Description
challengeId	string		The ID of the challenge for the choice recognition.
recorder	Recorder		Audio Recorder instance.
progressCb	Function		Callback function to call if progressed results are being used.

Return:

If all good the result will have the recognition performed. Otherwise it will return an error.

public prepareAnalysisChallenge(analysisId: string, challengeId: string): Promise<*> source

import {prepareAnalysisChallenge} from 'itslanguage/api/challenges/pronunciation/analysis.js'

Prepare the backend by telling it which challenge it can expect by a new analysis.

Params:

Name	Type	Attribute	Description
analysisId	string		The ID of the analysis to attache the challenge to.
challengeId	string		The ID of the challenge that belongs to a specific analysis.

Return:

Promise with the result of the init_challenge call.

public prepareAudioForChoiceRecognition(recognitionId: string, recorder: Recorder): Promise source

import {prepareAudioForChoiceRecognition} from 'itslanguage/api/challenges/choice/recognition.js'

The audio that is to be uploaded for recognition is streamed to the server. Some information is required in order for the server to be able to store and use the audio correctly.

Params:

Name	Type	Attribute	Description
recognitionId	string		The ID of the recognition to initialise the audio for.
recorder	Recorder		Instance of a recorder. The metadata will be extracted elsewhere.

Return:

If it fails an error will be returned. Otherwise nothing will be returned.

See:

https://itslanguage.github.io/itslanguage-docs/websocket/choice_recognitions/index.html#initialising-audio-for-uploading

public prepareAudioForPronuncationAnalysis(analyseId: string, recorder: Recorder): Promise source

import {prepareAudioForPronuncationAnalysis} from 'itslanguage/api/challenges/pronunciation/analysis.js'

Prepare the backend for our audio.

Params:

Name	Type	Attribute	Description
analyseId	string		The Analysis that belongs to the audio.
recorder	Recorder		The recorder to get specs from.

Return:

Result of preparing the audio.

public prepareChoiceRecognition(): Promise source

import {prepareChoiceRecognition} from 'itslanguage/api/challenges/choice/recognition.js'

This is the starting point for a choice recognition. A unique recognition id is generated, which serves a leading role in the recognition. Each other call requires the recognition id as a parameter.

If other RPCs are called without this RPC being called first, the error nl.itslanguage.session_not_initialised will be returned.

Return:

Returns a promise. When successfully the ID of the recognition is returned.

See:

https://itslanguage.github.io/itslanguage-docs/websocket/choice_recognitions/index.html#initialising-a-choice-recognition

public prepareChoiceRecognitionChallenge(recognitionId: string, challengeId: string): Promise source

import {prepareChoiceRecognitionChallenge} from 'itslanguage/api/challenges/choice/recognition.js'

Before performing the recognition, a WFST needs to be prepared for the challenge. When the RPC is called, the challenge is initialised asynchronously. When the challenge is to be used, the server automatically waits for the challenge initialisation to finish. If the initialisation results in an error, the error is relayed to the client.

Params:

Name	Type	Attribute	Description
recognitionId	string		The ID of the recognition to prepare the challenge for.
challengeId	string		The ID of the challenge to prepare.

Return:

If succesful the promise returns nothing. On error, there will be an error.

See:

https://itslanguage.github.io/itslanguage-docs/websocket/choice_recognitions/index.html#initialise-choice-challenge

public preparePronunciationAnalysis(): Promise | Promise<*> source

import {preparePronunciationAnalysis} from 'itslanguage/api/challenges/pronunciation/analysis.js'

Create a new analysis and return the ID.

Return:

Promise | Promise<*>

The result will hold the ID for the analysis.

public prepareServerForAudio(id: string, recorder: MediaRecorder | Recorder, rpc: string): Promise source

import {prepareServerForAudio} from 'itslanguage/api/utils/audio-over-socket.js'

Send the recorder settings to the websocket server to initialize it.

The reserved ID (passed in the parameters) is returned once the promise is resolved.

Params:

Name	Type	Attribute	Description
id	string		The reserved ID for the audio.
recorder	MediaRecorder \| Recorder		The recorder which has been set up to record.
rpc	string		The RPC to use to initialize the websocket server.

Return:

The promise which resolves when the websocket server is ready for the audio.

Emit:

websocketserverreadyforaudio

When the websocket server has been prepared for and is ready to receive the audio.

public recogniseChoiceRecognition(recognitionId: string, progressCb: Function): Promise<Object> source

import {recogniseChoiceRecognition} from 'itslanguage/api/challenges/choice/recognition.js'

After completing the streaming of the audio, the recognition can be performed.

Params:

Name	Type	Attribute	Description
recognitionId	string		The ID of the recognition to recognise on.
progressCb	Function		A function that could be called if progressed results are required.

Return:

It will return a object with the recognition result if successful.

See:

https://itslanguage.github.io/itslanguage-docs/websocket/choice_recognitions/index.html#perform-the-recognition

public request(method: string, url: string, body: *, headers: Headers): Promise<Object> source

import {request} from 'itslanguage/api/communication/index.js'

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.

Params:

Name	Type	Attribute	Description
method	string		The request METHOD ('GET', 'POST', 'PUT', 'DELETE').
url	string		The location to send the request to.
body	*	optional	Anything which needs to be sent somewhere.
headers	Headers	optional	Extra headers to send with the request.

Return:

The response of the made request.

public streamAudioForPronunciationAnalysis(analyseId: string, recorder: Recorder): Promise source

import {streamAudioForPronunciationAnalysis} from 'itslanguage/api/challenges/pronunciation/analysis.js'

Us the provided recorder to stream/send the recorded audio to the backend.

Params:

Name	Type	Attribute	Description
analyseId	string		The ID of the analysis we're receiving audio for.
recorder	Recorder		Instance of an Recorder.

Return:

Stream result.

public updateSettings(newSettings: Object) source

import {updateSettings} from 'itslanguage/api/communication/index.js'

Update the settings with the newSettings.

Params:

Name	Type	Attribute	Description
newSettings	Object		The settings to inject/update.

Throw:

Error

When the given newSettings is something other than a object.

public waitForUserMediaApproval(id: string, recorder: MediaRecorder): Promise source

import {waitForUserMediaApproval} from 'itslanguage/api/utils/audio-over-socket.js'

Wait for the recorder to get the permission for user media.

The reserved ID (passed in the parameters) is returned once the promise is resolved.

Params:

Name	Type	Attribute	Description
id	string		The reserved ID for the audio.
recorder	MediaRecorder		The recorder for which to wait.

Return:

The promise which resolves if the user has allowed us to record them.

public writeAudioForChoiceRecognition(recognitionId: string, recorder: Recorder): Promise source

import {writeAudioForChoiceRecognition} from 'itslanguage/api/challenges/choice/recognition.js'

The streaming works by repeatedly calling this RPC. Each time the RPC is called, the data will be appended to an audio file on the server.

Params:

Name	Type	Attribute	Description
recognitionId	string		The ID of the recognition for which to upload audio.
recorder	Recorder		Instance of a recorder. The data will be fetched from it.

Return: