Keiser Metrics SDK
For a more information about this SDK visit the Keiser Developer Zone.
To play around with the SDK try out the Keiser Metrics SDK REPL.
To see the full SDK API view the Keiser Metrics SDK Documentation.
Install with npm:
npm install @keiser/metrics-sdk
Import the SDK package 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. The default implementation for browsers uses a WebSocket connection, but it will fall back to a normal HTTP request strategy if WebSockets are not supported. The NodeJS implementation will always use HTTP requests.
Metrics instance is a connection handler with access to only limited information. To access user specific information a
UserSession must be created by authenticating through one of 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
The result of an authentication request is a
UserSession which contains methods for interacting with the user's data as well as mechanisms for controlling the session.
To restore an authenticated session, store the refresh token string and use the
authenticateWithToken authentication mechanism to restore the session. The refresh token needs to be stored in a secure place that will persist between sessions (ie: Local Storage) and is valid for 90 days from it's creation.
localStorage.setItemrefreshTokenKey, userSession.refreshTokenuserSession.onRefreshTokenChangeEvent.subscribe// On next application start
Accessing User Data
All properties exposed by the
User class and it's children are instances that are generated 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.
This means that separate instances will also be out of sync as changes to one instance will not be reflected in other instances. The
reload() method available on most classes will bring the instance in sync with the current server state.
console.loguserProfile1 === userProfile2 // Output: falseconsole.loguserProfile1.name === userProfile2.name // Output: trueawait userProfile1.updateconsole.loguserProfile1 === userProfile2 // Output: falseconsole.loguserProfile1.name === userProfile2.name // Output: falseawait userProfile2.reloadconsole.loguserProfile1 === userProfile2 // Output: falseconsole.loguserProfile1.name === userProfile2.name // Output: true
// Recommended usage example
User data methods (ex:
user.getEmailAddresses()) will return an ordered array of class instances. These arrays have an extended
meta property which contains the parameters used to query the array, the sorting properties, and a
totalCount property which is the total number of instances associated with the parent class. By default these method will limit responses to
// Default call will return 20 entities with uncertain sorting// Will return 10 entities, sorted by Email property in ascending order, starting at ordered entity 1 (first)// Same sorting as previous call, but now will return the elements starting at ordered entity 31 (3rd page of entities)// Will return 10 entities that contain "@gmail.com", sorted and ordered
All errors are handled by throwing inside the method call with the expectation of a
try/catch to catch the error.
All errors will be thrown as a typed error instance corresponding to the reason for the error, with the global
Error as the base instance, and an intermediate category type inheritance (for easier bucketing).
|Request||Issue with the parameters provided for the request|
|Session||Issue with the session instance (session is no longer valid)|
|Server||Issue with the server (potentially overloaded or offline)|
|Connection||Issue with connection to server|
|Missing Params||Request||Parameters are missing from action (potentially
|Invalid Credentials||Request||Invalid login credentials (don't match any active user)|
|Validation||Request||Parameters are present but do not pass validation|
|Unknown Entity||Request||Request target does not exist (deleted or never existed)|
|Duplicate Entity||Request||Cannot create a new instance because identical one exists|
|Unauthorized Resource||Request||Insufficient permissions to access the target|
|Action Prevented||Request||Request cannot be performed for reason other than those above (edge cases)|
|Facility Access Control||Request||Request is prevented due to facility access control limitations|
Copyright and License
Copyright © 2020 Keiser Corporation.
The Keiser Metrics SDK source code and distributed package are made available through the MIT license.
Using any of the APIs made available through the Keiser Metrics SDK to communicate with Keiser Metrics make you subject to the following agreements. Please read all documents in their entirety as they govern your use of the APIs and Keiser Metrics servers.