@jifeline/core

Core library

The Core library contains all the core functionality that is needed to work with the different libraries implementing the Jifeline public API's.

The Core library provides modules for:

• performing HTTP requests
• handling Websocket implementations
• dealing with internationalization
• authentication at AWS Cognito

In order to use these libraries, simply import it with ES6 import statements. The namespace is @jifeline, so the full import path would be; @jifeline/core.

For upgrading from v0 to v1, check the RELEASE-NOTES-v1.md.

Usage of the library

The core library needs configuration in order to make the modules work. The configuration exists of which API is requested. These are the interfaces of the different configurations;

interface IConfig {
  auth: IAuthConfig,
  http: IHttpClientConfig,
  ws: IWsClientConfig
}

/**
 * In v1.0.0 the IAuthConfig has been changed due to the upgrade of AWS Amplify from v5 to v6.
 */
interface IAuthConfig {
  aws?: {
    userPoolId: string;
    userPoolClientId: string;

    identityPoolId?: string;

    federated?: { 
      oauth: {
        domain: string, // The domain of the Jifeline identity provider.
        scopes: OAuthScope[]
        redirectSignIn: string[]; // The redirect urls after sign in (see Amplify docs).
        redirectSignOut: string[]; // The redirect urls after sign out, can't be the same as redirectSignIn (see Amplify docs).
        responseType: 'code' | 'token';
      } 
    };
  };

  /** 
   * Set the AWS User Pool ID.
   * @deprecated use userPoolId instead.
   */
  awsUserPoolId?: string;

  /**
   * Set the AWS user pool web client id.
   * @deprecated use userPoolClientId instead.
   */
  awsUserPoolWebClientId?: string;
}

interface IHttpClientConfig {
  apiBaseUrl: string;
}

interface IWsClientConfig {
  wsBaseUrl: string;
}

Set this config when using a module in order to make the Core library work.

import { httpClient, wsClient, auth, IAuthConfig, IHttpClientConfig, IWsClientConfig } from '@jifeline/core';

// Replace with API base url for given environment.
const httpConfig: IHttpClientConfig = {
  apiBaseUrl: 'customer-api-location'
};

// Replace with WS base url for given environment.
const wsConfig: IWsClientConfig = {
  wsBaseUrl: 'customer-ws-location'
};

// Replace with AWS Cognito config for given environment.
const authConfig: IAuthConfig = {
  aws: {
    userPoolId: 'user-pool-id',
    userPoolClientId: 'user-pool-client-id',
  }
};

// Configure all the needed modules before using core features.
httpClient.configure(httpConfig);
wsClient.configure(wsConfig);
auth.configure(authConfig);

After setting up all the core modules, the auth module can be used to sign in so all the @jifeline features can be used.

// Login with pin or username password to get a bearer token in order to cummunicate with the Customer API.
auth
  .loginPinV2('b86d0d8b-7022-11ea-8095-00163e561f6d', '12345')
  .subscribe({
    next: tokens => console.log('authenticated with connector / pin', tokens),
    error: err => console.error('authentication failed with connector / pin', err)
  });

auth
  .loginUsername('username', 'password')
  .subscribe({
    next: tokens => console.log('authenticated with username / password', tokens),
    error: err => console.error('authentication failed with username / password', err)
  });

auth
  .loginOtp('provided-otp', 'password')
  .subscribe({
    next: tokens => console.log('authenticated with OTP', tokens),
    error: err => console.error('authentication failed with OTP', err)
  });

It is also possible to perform a federated login. If this is desired, contact Jifeline in order to set up the configuration. After that, the loginFederated feature can be used.

auth
  .loginFederated({ 
    provider: 'test-example-azure-ad-oidc', // ID of the Federated configuration in our identity provider. This ID is provided when Jifeline configured the trust between our identity provider and the federated identity provider. 
  })
  .subscribe({
    next: tokens => console.log('authenticated with federated sign in', tokens),
    error: err => console.error('authentication failed with federated sign in', err)
  });

From here all libraries can be used. See other libraries for more specificks.

Features

The Core library provides the following features:

• auth
• httpClient
• wsClient
• i18n

Auth

This module provides authentication features. These features will authenticate a user at AWS Cognito and, if enabled, validate MFA. When authentication is successful, it will store the session tokens provided by Cognito, and share them with the HTTP module. The HTTP module will add the session token as a bearer token to each HTTP request as authorization header in order to be able to communicate with the Jifeline Customer API.

The following functions are supported:

• configure
• configureTokenProvider
• LoginPin deprecated in favour of loginPinV2
• loginPinV2
• loginUsername
• loginFederated
• loginCustomTokenProvider
• loginOtp
• onMfaSoftwareTokenRequired
• onNewPasswordRequired
• confirmResetPassword
• setNewPassword
• logout
• isAuthenticated
• isAuthenticatedWithUpdates
• onAuthenticated
• onUnauthenticated
• getAccessToken
• getIdToken
• getCognitoBaseClient
• setMfaSoftwareToken
• isErrorReasonPasswordNotStrongEnough
• isPinCodeInvalidError
• isConnectorOfflineError

HTTP client

This module provides a wrapper around the Fetch API. The wrapper supports HTTP GET, POST, PUT, and DELETE calls. When provided by the Auth module, it will set the Authorization header. When provided by the i18n module, it will set the Accept-Language header. There is no need to use the HTTP client directly. All the endpoints are implemented in different libraries.

The following functions are supported:

• configure
• doGet
• doPost
• doPut
• doDelete
• setI18nClient
• onUnauthorized
• setGetAccessToken
• doRequest
• backoffRetry

WS client

The WS client is an implementation around the RxJS websocket subject. It connects to the websocket server, and uses the same connection to subscribe to different channels by different topics.

The following functions are supported:

• configure
• subscribeToChannel
• setGetAccessToken

I18n

This module provides a client which should be used for all topics around internationalization (i18n). An instance can be provided to the HTTP client, which will use it to determine the wanted Locale and add it to all requests via the Accept-Language header so the Jifeline Customer API knows in which language it needs to provide responses.

import { I18nClient, Locale, httpClient, IHttpClientConfig } from '@jifeline/core';

// Create a client with "en-GB" as default locale.
const i18nClient = new I18nClient();

// Or create one using a different default locale.
const i18nClientNl = new I18nClient(Locale.NlNl);

const httpConfig: IHttpClientConfig = { apiBaseUrl: 'customer-api-location' };

httpClient.configure(httpConfig, i18nClient);

// Or...
httpClient.configure(httpConfig, i18nClientNl);

The following functions are supported:

• getLanguageConfigurations
• setActiveLanguageConfiguration
• getActiveLanguageConfiguration