@relevance/core

Relevance.io TypeScript/Javascript SDK

This software development kit aims to provide a standard interface to connect to the Relevance.io APIs in TypeScript or JavaScript projects.

Getting started

Requirements

These are the general requirements for using this package:

• Node 12 or higher is recommended
• npm 6.14 or higher is recommended

Installation

To install from the public repositories, use:

npm install @relevance/core

Usage

Query services

The query SDK provides two main interfaces: the UserService and the RequestBuilder. The UserService is the one responsible for dispatching requests and the RequestBuilder is responsible for building query requests. Typical usage goes like this:

interface MySearchResult { first_name: string, last_name: string, age: number };
service = new QueryService<MySearchResult>('https://url/to/query/api');
request = new RequestBuilder()
    .addTerm('Smith')
    .addExtension('slice', [0, 50]);
service.search(request).then((results) => {
    console.log(results.results);
});

The search method returns a HttpRequest object, which is promise-like, but contains a few additional methods:

httpRequest = service.search(request);
httpRequest.abort();            // allows to abort request in-flight
httpRequest.then((results) => {
    console.log(httpRequest.getStatusCode());
}).catch((err) => {
    console.error(err);
});

Alternatively, the QueryBuilder can be used in lieu of the RequestBuilder to streamline query building using the core query extensions (assuming they are enabled on the server):

query = new QueryBuilder()
    .addFilter('first_name', '==', 'John')
    .setLimit(50)
    .addSort('last_name', 'desc');

User services

The user services connect to the user API server and consist of these services:

- `SessionService` is the main entry point that allows to generate `Session` objects, which are necessary to
  authenticate subsequent requests to the user and profile endpoints.
- The `UserService` allows to create users, update secrets and other core user features.
- The `ProfileService` allows to manipulate a user's private or public profile matching the schema that was
  defined on the server.
- The `RecoveryService` allows to perform recovery tasks like resetting a lost password.

Except for the RecoveryService which doesn't need authentication, a typical workflow will have you create a session token and then use it in the other services:

sessionService = new SessionService('https://url/to/user/api');
userService = new UserService(sessionService);
session = await sessionService.createSession('login', 'secret');
user = await userService.getUser('me');

When invoking methods, one can specify a token or leave it undefined, with the latter using the token from the last created session by the instance of the service.

Building and testing

To test a distribution, use:

npm run test            # runs the tests
npm run lint            # validates code syntax

Then build with:

npm run build

Development mode

This package provides an stream-lined way of locally installing dependencies, building and linking for a development environment. The "development mode" basically installs the dependencies and builds the package so that it can be used in cross-linked packages.

To use it, first install the dependencies in development mode:

npm run install:dev

When building, use:

npm run build:dev

This installs and builds the package as a global package that can be linked to other dependent packages without first having to publish it.

License

This code and its documentation is provided under the MIT License, bundled as the LICENSE file. All original rights are reserved to Relevance.io 2020-.