@keiser/metrics-sdk

Keiser Metrics SDK Library

Project

This library facilitates communication between the Keiser Metrics API and client software using a per-user authentication mechanism. Refer to the Keiser Developer Zone for more details about interacting with the Keiser Metrics API.

To play around with the SDK try out the Keiser Metrics SDK REPL.

To see the full SDK API view the Keiser Metrics SDK API.

Installation

Install with npm: npm install @keiser/metrics-sdk

Usage

Import the library root class and instantiate a Metrics connection instance. Each instance maintains a connection to the Keiser Metrics servers so only one instance should be created per an application. This instance handles multiplexing requests, throttling, and request retries automatically.

import Metrics from '@keiser/metrics-sdk'

const metrics = new Metrics()

Authentication

Create a UserSession by authenticating the user using on the available mechanisms:

• authenticateWithCredentials - Use email and password
• authenticateWithFacebook - Use Facebook OAuth flow
• authenticateWithGoogle - Use Google OAuth flow
• authenticateWithToken - Use a stored refresh token string

 const userSession = await metrics.authenticateWithCredentials({email: '[e-mail]', password: 'password'})

The UserSession instance includes session specific methods and accessors that will be used for a majority of operations. The user accessor returns an instance of the User class.

const profile = userSession.user.profile
console.log(`Hello ${profile.name}!`)

User Properties

All properties exposed by the User class and it's children are generating instances on access, so subsequent calls to the same property are not returning the exact same instance. It is recommended to keep accessed instances in scope using local references. This prevents memory leaks and improves performance when dealing with large data sets.

let userProfile1 = userSession.user.profile
let userProfile2 = userSession.user.profile
console.log(userProfile1 === userProfile2)
// Will output: false

// Recommended usage example
function generateUsername(user: User) {
  const name = user.profile.name

  return name ? name.replace(/\s/, '_').toLowerCase() : 'unknown_username'
}

Persisting Authentication

For maintaining the user authentication between sessions, store the refresh token string and use the authenticateWithToken authentication mechanism to start a new session for the same user. The refresh token needs to be stored in a secure place that will persist between sessions (ie: Local Storage).

const refreshTokenKey = 'refreshToken'
const userSession = await metrics.authenticateWithCredentials({email: '[e-mail]', password: 'password'})

localStorage.setItem(refreshTokenKey, userSession.refreshToken)

userSession.onRefreshTokenChangeEvent.subscribe(refreshToken => {
  // Will update token in local storage each time it is updated
  localStorage.setItem(refreshTokenKey, refreshToken)
})

Closing Connection

The base Metrics instance maintains an active connection until it is disposed, so it is recommended to dispose the connection by calling dispose() once the connection is no longer needed.

metrics.dispose()

API

The full API is available for exploration at Keiser Metrics SDK API.

Copyright and License

Copyright © 2020 Keiser Corporation under the MIT license.