npm package: @relevance/core
Description: Relevance.io libraries for TypeScript and JavaScript
Author: Relevance.io
Latest version: 1.0.6
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# 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-.