EnigmaBase JavaScript SDK
Official JavaScript SDK (browser and node) for interacting with the EnigmaBase API.
Installation
Node.js (via npm)
npm install enigmabase --save
const EnigmaBase = require("enigmabase");
...
OR if you are using es6 style imports (suitable also for bundlers like rollup and webpack):
import EnigmaBase from "enigmabase";
...
Browser (manually via script tag)
<script src="/path/to/dist/enigmabase.iife.js"></script>
OR if you are using JavaScript modules:
<script type="module">
import EnigmaBase from "/path/to/dist/enigmabase.es.js"
...
</script>
Examples
const client = new EnigmaBase('http://localhost:8090');
...
// list and filter "demo" collection records
const result = await client.Records.getList("demo", 1, 20, {
filter: "status = true && totalComments > 0"
});
// authenticate as regular user
const userData = await client.Users.authViaEmail("test@example.com", "123456");
// or as admin
const adminData = await client.Admins.authViaEmail("test@example.com", "123456");
// and much more...
More detailed API docs and copy-paste examples could be found in the API documentation for each service.
Definitions
Creating new client instance
const client = new EnigmaBase(
baseUrl = '/',
lang = 'en-US',
authStore = LocalAuthStore,
httpConfig = {},
);
Instance methods
Each instance method returns the
EnigmaBase
instance allowing chaining.
Method | Description |
---|---|
client.cancelRequest(cancelKey) |
Cancels single request by its cancellation token key. |
client.cancelAllRequests() |
Cancels all pending requests. |
client.send(reqConfig = {}) |
Sends an api http request. |
API services
Each service call returns a
Promise
object with the API response.
Resource | Description |
---|---|
Admins | |
🔓client.Admins.authViaEmail(email, password, bodyParams = {}, queryParams = {})
|
Authenticate an admin account by its email and password and returns a new admin token and admin data. |
🔐client.Admins.refresh(bodyParams = {}, queryParams = {})
|
Refreshes the current admin authenticated instance and returns a new admin token and admin data. |
🔓client.Admins.requestPasswordReset(email, bodyParams = {}, queryParams = {})
|
Sends admin password reset request. |
🔓client.Admins.confirmPasswordReset(passwordResetToken, password, passwordConfirm, bodyParams = {}, queryParams = {})
|
Confirms admin password reset request. |
🔐client.Admins.getList(page = 1, perPage = 30, queryParams = {})
|
Returns paginated admins list. |
🔐client.Admins.getFullList(batchSize = 100, queryParams = {})
|
Returns a list with all admins batch fetched at once. |
🔐client.Admins.getOne(id, queryParams = {})
|
Returns single admin by its id. |
🔐client.Admins.create(bodyParams = {}, queryParams = {})
|
Creates a new admin. |
🔐client.Admins.update(id, bodyParams = {}, queryParams = {})
|
Updates an existing admin by its id. |
🔐client.Admins.delete(id, bodyParams = {}, queryParams = {})
|
Deletes an existing admin by its id. |
Users | |
🔓client.Users.listAuthMethods(queryParams = {})
|
Returns all available application auth methods. |
🔓client.Users.authViaEmail(email, password, bodyParams = {}, queryParams = {})
|
Authenticate a user account by its email and password and returns a new user token and user data. |
🔓client.Users.authViaOAuth2(clientName, code, codeVerifier, redirectUrl, bodyParams = {}, queryParams = {})
|
Authenticate a user via OAuth2 client provider. |
🔐client.Users.refresh(bodyParams = {}, queryParams = {})
|
Refreshes the current user authenticated instance and returns a new user token and user data. |
🔓client.Users.requestPasswordReset(email, bodyParams = {}, queryParams = {})
|
Sends user password reset request. |
🔓client.Users.confirmPasswordReset(passwordResetToken, password, passwordConfirm, bodyParams = {}, queryParams = {})
|
Confirms user password reset request. |
🔓client.Users.requestVerification(email, bodyParams = {}, queryParams = {})
|
Sends user verification email request. |
🔓client.Users.confirmVerification(verificationToken, bodyParams = {}, queryParams = {})
|
Confirms user email verification request. |
🔐client.Users.requestEmailChange(newEmail, bodyParams = {}, queryParams = {})
|
Sends an email change request to the authenticated user. |
🔓client.Users.confirmEmailChange(emailChangeToken, password, bodyParams = {}, queryParams = {})
|
Confirms user new email address. |
🔐client.Users.getList(page = 1, perPage = 30, queryParams = {})
|
Returns paginated users list. |
🔐client.Users.getFullList(batchSize = 100, queryParams = {})
|
Returns a list with all users batch fetched at once. |
🔐client.Users.getOne(id, queryParams = {})
|
Returns single user by its id. |
🔐client.Users.create(bodyParams = {}, queryParams = {})
|
Creates a new user. |
🔐client.Users.update(id, bodyParams = {}, queryParams = {})
|
Updates an existing user by its id. |
🔐client.Users.delete(id, bodyParams = {}, queryParams = {})
|
Deletes an existing user by its id. |
Realtime (for node environments you'll have to install an EventSource polyfill beforehand, eg. https://github.com/EventSource/eventsource) |
|
🔓client.Realtime.subscribe(subscription, callback)
|
Inits the sse connection (if not already) and register the subscription. |
🔓client.Realtime.unsubscribe(subscription = "")
|
Unsubscribe from a subscription (if empty - unsubscibe from all registered subscriptions). |
Collections | |
🔐client.Collections.getList(page = 1, perPage = 30, queryParams = {})
|
Returns paginated collections list. |
🔐client.Collections.getFullList(batchSize = 100, queryParams = {})
|
Returns a list with all collections batch fetched at once. |
🔐client.Collections.getOne(id, queryParams = {})
|
Returns single collection by its id. |
🔐client.Collections.create(bodyParams = {}, queryParams = {})
|
Creates a new collection. |
🔐client.Collections.update(id, bodyParams = {}, queryParams = {})
|
Updates an existing collection by its id. |
🔐client.Collections.delete(id, bodyParams = {}, queryParams = {})
|
Deletes an existing collection by its id. |
Records | |
🔓client.Records.getList(collectionIdOrName, page = 1, perPage = 30, queryParams = {})
|
Returns paginated records list. |
🔓client.Records.getFullList(collectionIdOrName, batchSize = 100, queryParams = {})
|
Returns a list with all records batch fetched at once. |
🔓client.Records.getOne(collectionIdOrName, id, queryParams = {})
|
Returns single record by its id. |
🔓client.Records.create(collectionIdOrName, bodyParams = {}, queryParams = {})
|
Creates a new record. |
🔓client.Records.update(collectionIdOrName, id, bodyParams = {}, queryParams = {})
|
Updates an existing record by its id. |
🔓client.Records.delete(collectionIdOrName, id, bodyParams = {}, queryParams = {})
|
Deletes an existing record by its id. |
Logs | |
🔐client.Logs.getRequestsList(page = 1, perPage = 30, queryParams = {})
|
Returns paginated request logs list. |
🔐client.Logs.getRequest(id, queryParams = {})
|
Returns a single request log by its id. |
🔐client.Logs.getRequestsStats(queryParams = {})
|
Returns request logs statistics. |
Settings | |
🔐client.Settings.getAll(queryParams = {})
|
Fetch all available app settings. |
🔐client.Settings.update(bodyParams = {}, queryParams = {})
|
Bulk updates app settings. |
Caveats
The SDK client auto cancel duplicated pending requests.
For example, if you have the following 3 duplicated calls, only the last one will be executed, while the first 2 will be cancelled with error null
:
client.Records.getList("demo", 1, 20) // cancelled
client.Records.getList("demo", 1, 20) // cancelled
client.Records.getList("demo", 1, 20) // executed
To change this behavior, you could make use of 2 special query parameters:
-
$autoCancel
- set it tofalse
to disable auto cancellation for this request -
$cancelKey
- set it to a string that will be used as request identifier and based on which pending duplicated requests will be matched (default toHTTP_METHOD + url
, eg. "get /api/users?page=1")
Example:
client.Records.getList("demo", 1, 20); // cancelled
client.Records.getList("demo", 1, 20); // executed
client.Records.getList("demo", 1, 20, { "$autoCancel": false }); // executed
client.Records.getList("demo", 1, 20, { "$autoCancel": false }) // executed
client.Records.getList("demo", 1, 20, { "$cancelKey": "test" }) // cancelled
client.Records.getList("demo", 1, 20, { "$cancelKey": "test" }) // executed
To manually cancel pending requests, you could use client.cancelAllRequests()
or client.cancelRequest(cancelKey)
.
Development
# run unit tests
npm test
# build and minify for production
npm run build