Security News
npm Updates Search Experience with New Objective Sorting Options
npm has a revamped search experience with new, more transparent sorting options—Relevance, Downloads, Dependents, and Publish Date.
@keiser/metrics-sdk
Advanced tools
This SDK facilitates communication between a client system (ie: phone app, website, server) and Keiser Metrics. The SDK is written in TypeScript and supports both browser and NodeJS platforms.
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.
import Metrics from '@keiser/metrics-sdk'
const metrics = new Metrics()
When developing against a local deployment, or a mocking endpoint, configure the Metrics connection from the initial Metrics instantiation.
import Metrics from '@keiser/metrics-sdk'
const metrics = new Metrics({restEndpoint: 'http://localhost:8000/api', socketEndpoint: 'ws://localhost:8000/ws'})
The base 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 passwordauthenticateWithFacebook
- Use Facebook OAuth flowauthenticateWithGoogle
- Use Google OAuth flowauthenticateWithApple
- Use Apple OAuth flowauthenticateWithToken
- Use a stored refresh token stringconst userSession = await metrics.authenticateWithCredentials({email: 'demo@keiser.com', password: 'password'})
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 log-out a user, call teh logout()
method on the UserSession
.
await userSession.logout()
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.
const refreshTokenKey = 'refreshToken'
const userSession = await metrics.authenticateWithCredentials({email: 'demo@keiser.com', 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)
})
// On next application start
const refreshToken = localStorage.getItem(refreshTokenKey)
const userSession = await metrics.authenticateWithToken({token: refreshToken})
The UserSession
instance contains a user
property accessor for the authenticated user's User
class.
const userSession = await metrics.authenticateWithCredentials({email: 'demo@keiser.com', password: 'password'})
console.log(userSession.user.eagerProfile().name)
All properties exposed by the User
class and it's children readonly. Most classes have eager loaded associated classes which are accessed through function calls prefixed with eager
(ex: user.eagerProfile
). While the data for the eager classes is already stored, the class is not instantiated until the method is called and each call will instantiate a new class, so it is recommended to store the eager class locally. 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.
let userProfile1 = userSession.user.eagerProfile()
let userProfile2 = userSession.user.eagerProfile()
console.log(userProfile1 === userProfile2) // Output: false
console.log(userProfile1.name === userProfile2.name) // Output: true
await userProfile1.update({name: 'Pickle Rick'})
console.log(userProfile1 === userProfile2) // Output: false
console.log(userProfile1.name === userProfile2.name) // Output: false
await userProfile2.reload()
console.log(userProfile1 === userProfile2) // Output: false
console.log(userProfile1.name === userProfile2.name) // Output: true
// Recommended usage example
function generateUsername(user: User) {
const profile = user.eagerProfile()
return profile?.name ? profile.name.replace(/\s/, '_').toLowerCase() : 'unknown_username'
}
All model data is nested under it's parent associations in an tree structure stemming from the base session object (UserSession
, FacilitySession
). All model references are generated at access and will not be persisted in memory by the SDK so local references are necessary to persist data. Most associated data models will be accessed through async
method calls with the prefix get
for single model instantiations, and list
for multiple model instantiations.
// Variable `strengthExercises` will be an array containing up to 20 instances of strength exercises with 'back' in the exercise alias (name)
const strengthExercises = await userSession.getStrengthExercises({ defaultAlias: 'back', limit: 20 })
// Variable `strengthExercise` will contain a single strength exercise instance with 'id' equal to 1000
const strengthExercise = await userSession.getStrengthExercise({ id: 1000 })
All plural 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 20
instances.
// Default call will return 20 entities with uncertain sorting
const emailAddresses = await user.getEmailAddresses()
// Will return 10 entities, sorted by Email property in ascending order, starting at ordered entity 1 (first)
const firstPageOfEmailAddresses = await user.getEmailAddresses({sort: EmailAddressSorting.Email, ascending: true, limit: 10, offset: 0})
const totalNumberOfEmailAddresses = emailAddresses.meta.totalCount
// Same sorting as previous call, but now will return the elements starting at ordered entity 31 (3rd page of entities)
const thirdPageOfEmailAddresses = await user.getEmailAddresses({sort: EmailAddressSorting.Email, ascending: true, limit: 10, offset: 30})
// Will return 10 entities that contain "@gmail.com", sorted and ordered
const searchResultEmailAddresses = await user.getEmailAddresses({email: '@gmail.com', sort: EmailAddressSorting.Email, ascending: true, limit: 10, offset: 0})
All data models and properties are externally immutable and act as functional data structures (though the implementation is not purely functional). Properties will change with calls to methods on the model (update
, reload
, delete
). These mutating methods will always return a mutated instance of the model, but the existing model instance will also be mutated in place. There are no events emitted on mutation.
This restriction on direct property mutation preserves the integrity of the data within the SDK by ensuring the data always represents the actual data in the Metrics server.
// This will result in an error
profile.name = 'Rick Sanchez'
// Instead, issue an update
console.log(profile.name) // Outputs: 'Richard Sanchez'
await profile.update({ ...profile, name: 'Rick Sanchez' })
console.log(profile.name) // Outputs: 'Rick Sanchez'
Update calls are always full replacements of the model, so properties not included in the update
parameters will be cast to null
in the data model. Best practice is to expand the model and then override the property changes in the new model instance to ensure there is no unintended data loss.
// Performing an update with a partial property will result in loss of other properties.
console.log(profile.language) // Outputs: 'en'
await profile.update({ name: 'Rick Sanchez' })
console.log(profile.language) // Outputs: null
// Instead, expand the model to ensure that data is not lost
console.log(profile.language) // Outputs: 'en'
await profile.update({ ...profile, name: 'Rick Sanchez' })
console.log(profile.language) // Outputs: 'en'
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).
let userSession
try {
userSession = await metrics.authenticateWithCredentials({email: 'demo@keiser.com', password: 'wrongPassword'})
} catch (error) {
if (error instanceof RequestError) {
if (error instanceof InvalidCredentialsError) {
this.userCredentialsIncorrect()
} else if (error instanceof ValidationError) {
this.userCredentialsValidationError()
}
} else if (error instanceof ServerError) {
this.serverDown()
}
}
Name | Reason |
---|---|
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 |
Name | Category | Reason |
---|---|---|
Missing Params | Request | Parameters are missing from action (potentially null or undefined ) |
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 |
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()
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.
FAQs
Keiser Metrics SDK
The npm package @keiser/metrics-sdk receives a total of 1 weekly downloads. As such, @keiser/metrics-sdk popularity was classified as not popular.
We found that @keiser/metrics-sdk demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
npm has a revamped search experience with new, more transparent sorting options—Relevance, Downloads, Dependents, and Publish Date.
Security News
A supply chain attack has been detected in versions 1.95.6 and 1.95.7 of the popular @solana/web3.js library.
Research
Security News
A malicious npm package targets Solana developers, rerouting funds in 2% of transactions to a hardcoded address.