Overview

About the SDK

The Envizage SDK is a set of Javascript methods that can be used to facilitate interaction with the Envizage API. The SDK can be used in both client-side and server-side (Node.js) Javascript and Typescript code. Type declarations are included.

Http client

The SDK requires an HTTP client implementation. The user can implement their own client or use a custom client implementation included in the SDK.

Pre-requisites

The @envizage/model NPM package is a peer dependency for the SDK. It includes interfaces and mappings for entities used in the API. Make sure that a version equal to or newer than the minimum specified in the SDK project is installed in your project. You can install the @envizage/model package using the following command:

npm install --save @envizage/model

Or, if you are using Yarn:

yarn add @envizage/model

Installation

The SDK package can be installed as a usual NPM package:

npm install --save @envizage/services

Or, using Yarn:

yarn add @envizage/services

Usage

HTTP client

An HTTP client implementation is required as a dependency for all other services included in the SDK. The HTTP client that will be injected has to implement the IHttpClient interface:

export interface IHttpClient {
  get: <T>(url: string, params?: Map<string, string>, headerMap?: string[][]) => Promise<T>,

  post: <T, U>(url: string, body: T, params?: Map<string, string>, headerMap?: string[][]) => Promise<U>,

  put: <T, U>(url: string, body: T, params?: Map<string, string>, headerMap?: string[][]) => Promise<U>,

  remove: <T>(url: string, params?: Map<string, string>, headerMap?: string[][]) => Promise<T>
}

A user of the SDK can either implement that interface or import a ready fetch-based implementation that comes with the SDK:

import { HttpClient } from "@envizage/services";

A wrapper is also available to intercept requests before/after the HTTP client interacts with the API that can be used to add headers to HTTP requests. The following example intercepts HTTP requests and adds the basic headers required in every request to the API:

import { withInterceptor, HttpClient } from '@envizage/services';

const simpleClient = withInterceptor((url, params, headerMap, body) => {
  const clonedHeaders = headerMap ? (JSON.parse(JSON.stringify(headerMap)) as [string, string][]) : [];
  clonedHeaders.push(['Accept', 'application/json']);
  clonedHeaders.push(['Content-type', 'application/json']);

  return {
    url, params, headerMap: clonedHeaders, body
  }
})(HttpClient);

Service initialization

Each service is a class that needs to be instantiated to access the API. A new object can simply be created and used in any Javascript app. Note that all services except for the account management ones (see appendix) require authorization headers added to the HTTP requests so the HTTP client has to accomodate that requirement.

import { LivingExpenseService } from '@envizage/services';

const apiUrl = 'https://api.envizage.me';
const userEmail = 'user@mail.com';
const userPass = 'userPass';

const unauthorizedClient = withInterceptor((url, params, headerMap, body) => {
  const clonedHeaders = headerMap ? (JSON.parse(JSON.stringify(headerMap)) as [string, string][]) : [];
  clonedHeaders.push(['Accept', 'application/json']);
  clonedHeaders.push(['Content-type', 'application/json']);

  return {
    url, params, headerMap: clonedHeaders, body
  }
})(HttpClient);


const loginService = new LivingExpenseService(unauthorizedClient, apiUrl);

const loginResponse = await loginService.login({
    emailAddress: userEmail,
    password: userPass
});

const token = loginResponse.token.accessToken;

const authorizedClient = withInterceptor((url, params, headerMap, body) => {
  const clonedHeaders = headerMap ? (JSON.parse(JSON.stringify(headerMap)) as [string, string][]) : [];
  clonedHeaders.push([HttpHeaders.Authorization, 'Bearer ' + token]);
  return {
    url, params, headerMap: clonedHeaders, body
  }
})(unauthorizedClient);

const livingExpenseService = new LivingExpenseService(authorizedClient, apiUrl);

const livingExpenseResponse = await livingExpenseService.query({
    page: 0,
    size: 2000,
    sort: PageableSort.ASC
});

The user has to initialize the services and can use different options depending on the project's framework, for example the Angular service injection mechanism can be used to initialize the services if that framework is used.

Appendix

The following list contains all services available in the SDK: