enigmabase

EnigmaBase JavaScript SDK

Official JavaScript SDK (browser and node) for interacting with the EnigmaBase API.

• Installation
• Examples
• Definitions
• Caveats
• Development

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("[e-mail]", "123456");


// or as admin
const adminData = await client.Admins.authViaEmail("[e-mail]", "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 to false 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 to HTTP_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