@quivers/browser
v0.2.1
Published
This is the official browser jasvascript package for connecting to the Quivers Public API.
Downloads
5
Readme
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)
- [email protected]
- [email protected]