@quivers/browser

Quivers JavaScript SDK

This is the Official Quivers JavaScript SDK. It allows for an easy way to interface with the Quivers Public API. This library is intended to be used in the browser. For a node.js distribution, please see Quivers.SDK.NodeJS.

The latest version of the SDK is always available at https://cdn.quivers.com/javascript-sdk/quivers.min.js, there is also a non-minified version.

If you are looking to access a specific version, these are also available and archived. https://cdn.quivers.com/javascript-sdk/quivers-0.0.1.min.js for example. You can target any available version, however it is not guaranteed that older versions will work as expected.

How to Use

The Quivers SDK exposes a class Quivers, which can be instantiated with options to specify the target environment (prod by default), if a specific instance of jQuery should be used, and if this instance should use websockets to communicate with the API (if supported).

var quivers = new Quivers({
	environment: "dev" || "test" || "demo" || "prod", //(default:prod)
	jquery: jQuery, //default is window.jQuery
	websocket: true || false, //(default: true)
	setUser: true || false //(default:true)
}, function (quivers) {
   console.log("Quivers is ready!");
});

If setUser is true and there is an existing authorization cookie, then upon instantiation, the SDK will call users/current using that authorization cookie. If the result is successful, the user property of that instance of the class will be set to the currently logged in user's details. The purpose of the callback function that is the last argument is to wait until that process is completed. If setUser is false, there is no need to provide a callback function, the SDK will be ready to use immediately.

Methods

Quivers.get(route, data, callback)

This will perform a GET request against a given endpoint (e.g. users/current). the data will be appeneded as query parameters to the route (e.g. business/search & {pagesize:1} will transform the route to businesses/search?pagesize=1).

The callback function has three arguments, error, result, and xhr. xhr will not be returned if the API request was done over websockets.

Quivers.post(route, data, callback)

This will perform a POST request against a given endpoint (e.g. users/register). the data will JSON stringified and passed to the body (query parameters should be passed as part of the route when using post()).

The callback function has three arguments, error, result, and xhr. xhr will not be returned if the API request was done over websockets.

Quivers.delete(route, callback)

This will perform a DELETE request against a given endpoint (e.g. auth/logout).

The callback function has three arguments, error, result, and xhr. xhr will not be returned if the API request was done over websockets.

Quivers.auth(emailOrCredentialsObject, password, callback)

This method accepts either a credentials object as the first argument, or an email and password for the first two arguments. The credentials object is formatted as...

{
   email: email,
   password: password
}

This method will authenticate the user against the Quivers API. If it is successful, an authorization token will be stored as a cookie, which will be used to authenticate further requests until the cookie either expires, or the cookie is deleted. Additionally, the details of the currently authenticated user will become available by accessing this.user where this is your instance of Quivers (this user property will be available once the onReady function fires when instantiating the Quivers class).

The callback function has three arguments, error, user, and xhr. xhr will not be returned if the API request was done over websockets.

Quivers.unauth(callback)

This method will log a user out of the API (if they have a valid authentication token), and will destroy the authorization cookie created from Quivers.auth().

The callback function has three arguments, error, user, and xhr. xhr will not be returned if the API request was done over websockets.

Developing this Project

All code for the Quivers library is available within ./quivers.js. When working with this project, follow the standard Quivers development & deployment workflows.

Deployment

When a commit is pushed to the master branch of this repository, Bitbucket Pipelines will attempt to deploy the project. It will minify the library, and sync it to S3: https://cdn.quviers.com/javascript-sdk.

Before commiting to master, ensure that you have updated the version in both ./package.json and within ./quivers.js, as otherwise, you may unintentionally override an archived version with the latest version.

Author

• Justin Frenzel (Product Development Manager @ Quivers)
• [e-mail]
• [e-mail]