Envizage SDK Docs
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.
You can install the @envizage/model package running either of the following commands (NPM or Yarn):
- NPM
- Yarn
npm install --save @envizage/model
yarn add @envizage/model
Make sure that a version equal to or newer than the minimum specified in the SDK project is installed in your project.
Installation
The SDK package can be installed as a usual NPM package or with Yarn:
- NPM
- Yarn
npm install --save @envizage/services
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.
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:
| Service name | Methods |
|---|---|
| PhysicalAssetService | query, get, create, update, delete |
| PortfolioAssetService | query, get, create, update, delete |
| PortfolioFinancialAssetService | query, get, create, update, delete |
| PropertyAssetService | query |
| InvestmentPropertyAssetService | query, get, create, update, delete |
| ResidentialPropertyAssetService | query, get, create, update, delete |
| AssetForPersonService | queryForPerson |
| PortfolioAssetForPersonService | query, get, create, update, delete |
| PortfolioFinancialAssetForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| ResidentialPropertyAssetForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| InvestmentPropertyAssetForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| UserConfigurationService | queryForComponent, queryForProfile, get, create, update, delete |
| LivingExpenseService | query, get, create, update, delete |
| MortgageExpenseService | query, get, create, update, delete |
| PortfolioContributionExpenseService | query, get, create, update, delete |
| RentExpenseService | query, get, create, update, delete |
| EmployeePensionContributionExpenseForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| InsurancePremiumExpenseForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| LivingExpenseForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| MortgageExpenseForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| PortfolioContributionExpenseForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| RentExpenseForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| EmployerPensionContributionIncomeService | query, get, create, update, delete |
| InsuranceIncomeService | query, get, create, update, delete |
| RentIncomeService | query, get, create, update, delete |
| UnearnedIncomeService | query, get, create, update, delete |
| EarnedIncomeForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| InsuranceIncomeForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| PensionAnnuityIncomeForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| PensionDrawdownIncomeForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| PensionLumpSumIncomeForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| StatePensionIncomeForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| RentIncomeForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| UnearnedIncomeForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| EmployerPensionContributionIncomeForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| StatePensionIncomeForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| TypedGoalService | query, get, create, update, delete |
| TypedGoalForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| MortgageLiabilityService | query, get, create, update, delete |
| OtherSecuredLiabilityService | query, get, create, update, delete |
| UnsecuredLiabilityService | query, get, create, update, delete |
| MortgageLiabilityForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| OtherSecuredLiabilityForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| UnsecuredLiabilityForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| PrimaryPersonService | get, update |
| PartnerPersonService | get, create, update, delete |
| ParentPersonService | query, get, create, update, delete |
| ChildPersonService | query, get, create, update, delete |
| PrimaryPersonService | get, get, update, delete |
| CriticalIllnessInsuranceForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| DisabilityInsuranceForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| LifeInsuranceForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| MortgageLifeInsuranceForPersonService | queryForPerson, getForPerson, createForPerson, updateForPerson, deleteForPerson |
| FinancialAssetClassService | query |
| FinancialAssetProfileService | query |
| FinancialAssetWrapperService | query |
| ScenarioService | query, get, create, load, update, clone, replace, execute, diagnose, diff |
| LoginService | login, loginUser |
| RegistrationService | register |
| TokenService | getClientToken, refresh, revoke |
| ResetPasswordService | resetPassword |
| TermsOfUseService | getCurrent, query, get, getAcceptance, create, update, updateAcceptance, delete |
| ResultsService | get |
| DiagnosticResultsService | get |