Canopy Toolkit for Javascript

Usage

Installation

yarn add @canopy-pte-ltd/canopy-toolkit

# or 

npm install @canopy-pte-ltd/canopy-toolkit

Client Options

The following options are supported when creating or restoring a client.

Note: Use the same set of options for both creating and restoring a client.

export type ClientOptions = {
  // The API Server to connect to
  apiServer: string;

  // The WebSocket server to connect to (Optional)
  websocketServer?: string;

  // Should the Websocket Proxy be disabled (Default: false)
  disableWebsocketProxy?: boolean;

  // The API Version to use (Default: v1)
  apiVersion?: string;

  // The App ID to set in the requests (Default: Canopy JS SDK)
  appId?: string;

  // The locale the responses should be in (Default: en)
  locale?: string;

  // Enable logging to the console (Default: false)
  enableLogging?: boolean;

  // Persist the login session to localStorage (Default: false)
  persistSession?: boolean;

  // The localStorage key to persist under (Default: canopy-session)
  persistSessionKey?: string

  // HTTP Proxy server (Works only inside Node.js - requires https-proxy-agent)
  httpProxyServer?: string;

  // Log websocket response time metrics (Default: false)
  logWebsocketMetrics?: boolean;

  // Callback to invoke when token is refreshed (Optional)
  onTokenRefresh?: () => void;

  // Callback to invoke when a user is logged in (Optional)
  onUserLogin?: () => void;

  // Callback to invoke when user is logged out (Optional)
  onUserLogout?: (previousSession: SessionResponse) => void;

  // Callback to invoke when the user's session times out. (Optional)
  onSessionTimeout?: (previousSession: SessionResponse) => void;
};

Authentication

Username + password login

import { CanopyClient } from '@canopy-pte-ltd/canopy-toolkit';

// Create the client
// - The client can be created in a common place and shared across the app.
const client = new CanopyClient({
  apiServer      : 'https://dev-api-gateway.kurtosys.org',
  persistSession : true
});

// Login with username & password
await client.login(username, password);

2FA code required

import { TwoFactorCodeRequired } from '@canopy-pte-ltd/canopy-toolkit';

• client.login would raise a TwoFactorCodeRequired exception.

• Get the MFA code from the user and call client.responseToLoginChallenge

  await client.respondToLoginChallenge(123587);

2FA activation required

import { TwoFactorActivationRequired } from '@canopy-pte-ltd/canopy-toolkit';

• client.login would raise a TwoFactorActivationRequired exception.

• The exception would contain a response parameter with the 2FA secret key using with a QR Code is to be generated and displayed.

• Request the user to scan the QR code into their authentication application

• Get the MFA code from the user and call client.responseToLoginChallenge

  await client.respondToLoginChallenge(123587);

Password reset is required

This login challenge is currently unsupported by this library

import { PasswordResetRequired } from '@canopy-pte-ltd/canopy-toolkit';

• client.login would raise a PasswordResetRequired exception.
• Request the user to login in Visualizer to reset the password.

Restore a session

On page-refresh, the existing user session if any can be restored into the client as long as the session is valid.

import { CanopyClient } from '@canopy-pte-ltd/canopy-toolkit';

const preAuthenticatedClient = CanopyClient.restoreSession({
  apiServer      : 'https://dev-api-gateway.kurtosys.org',
  persistSession : true
});

If a valid session is not available to restore from, one of the following exceptions will be thrown. In that case, create a fresh client and log the user in using the login methods documented above.

• SessionNotFoundError - a session could not be found
• SessionRestoreError - a session was found but an error occurred while trying to restore it
• SessionExpiredError - a session was found, but it was expired.

Making requests

Request Options:

export type RequestOptions = {
  // The javascript object to send as json (Does not apply to GET)
  data?: any;
  
  // Should the request be made via websocket (default: false)
  useWebsocket?: boolean;
  
  // Should the accounts information be skipped from the query parameters (default: false)
  withoutAccounts?: boolean;
  
  // Should the namespace prefix (eg. /api/v1) be skipped (default: false) 
  withoutNamespace?: boolean;
  
  // Override the auth token to use
  authToken?: string | boolean;
  
  // List of user accounts to make the request for (default: none)
  accounts?: (number | string)[] | null;
  
  // Additional headers to set
  headers?: KeyValueParams;
  
  // Should the headers set here replace the default headers added to all requests
  replaceHeaders?: boolean;
  
  // Call the api as a specific user ID
  asUser?: number | string;
  
  // Query parameters to set
  queryParams?: KeyValueParams;
  
  // API Version to use (eg. v1) 
  apiVersion?: string;
};

Methods

All methods support the request options documented above as the last parameter.

// GET /api/v1/user_details
const response = await client.get<ResponseType>('user_details');

// POST /api/v1/user_details
const response = await client.post<ResponseType>('user_details', {
  someData: 'xyzzy'
});

// PUT /api/v1/user_details
const response = await client.put<ResponseType>('user_details', {
  someData: 'xyzzy'
});

// PATCH /api/v1/user_details
const response = await client.patch<ResponseType>('user_details', {
  someData: 'xyzzy'
});

// DELETE /api/v1/user_details
const response = await client.delete<ResponseType>('user_details');

Logging out

await client.logout();