xcoobee-sdk
v1.4.3
Published
The XcooBee SDK is a facility to abstract lower level calls and implement standard behaviors. The XcooBee team is providing this to improve the speed of implementation and show the best practices while interacting with XcooBee.
Downloads
5
Readme
XcooBee JavaScript SDK
The XcooBee SDK is a facility to abstract lower level calls and implement standard behaviors. The XcooBee team is providing this to improve the speed of implementation and show the best practices while interacting with XcooBee.
Generally, all communication with XcooBee is encrypted over the wire since none of the XcooBee systems will accept plain traffic. All data sent to XcooBee from you and vice versa is going to use encryption. In addition, non-bee event communication to you is also signed using your PGP key.
If you need to generate new PGP keys you can login to your XcooBee account and go to the Settings
page to do so.
XcooBee systems operate globally but with regional connections. The SDK will be connecting you to your regional endpoint automatically.
There is detailed and extensive API documentation.
Instalation
For Node JS projects:
npm install xcoobee-sdk --save
For browser projects:
Use our CDN:
Use from our CDN distribution point: You can use this pattern.
https://app.xcoobee.net/scripts/sdk/[version]
Available versions:
- xcoobee-sdk-1.0.0.web.js
- xcoobee-sdk-1.4.0.web.js
- xcoobee-sdk-1.4.1.web.js
A fully formed url for you script tag would be
<script src='https://app.xcoobee.net/scripts/sdk/xcoobee-sdk-1.0.0.web.js' />
Build yourself:
- Clone repo from GitHub.
git clone https://github.com/XcooBee/xcoobee-js-sdk.git
- then run the following node commands
npm install
npm run build
- You should have a minified js file like
xcoobee-sdk-1.0.0.web.js
in the/dist
directory. You can use it in your web project via script tags.
<script src='xcoobee-sdk-1.0.0.web.js' />
Don't forget that if you need to use the openpgp to decrypt payloads you need to load the OpenPGP library files as well. Either via the openpgp CDN or from your own site. You can use cdnjs via https://cdnjs.com/libraries/openpgp
or our https://app.xcoobee.net/scripts/sdk
.
<script src='https://app.xcoobee.net/scripts/sdk/openpgp.min.js' />
Example of load with openpgp library all from your own source:
<script src='openpgp.min.js' />
<script src='xcoobee-sdk-1.4.1.web.js' />
Usage
Before using the SDK, it needs to be configured. Once created, the configuration can be set on the SDK instance. In this case, each function call will fallback to using this configuration. Alternatively, you may pass a reference to a configuration instance to each function call. This passed configuration will take precedence over any configuration set on the SDK instance.
CommonJS:
const XcooBee = require("xcoobee-sdk");
or ES6:
import XcooBee from "xcoobee-sdk";
The config object
The config object carries all basic configuration information for your specific setup and use. There are two ways to instantiate a config object. The first way is to use the constructor directly. The second way is to use the constructor indirectly via an utility function.
Options
const options = {
apiKey: 'YourApiKey',
apiSecret: 'YourApiSecret',
campaignId: 'TheIdOfOneOfYourCampaigns',
pgpSecret: 'YourPGPSecret',
pgpPassword: 'YourPGPPassphrase',
};
where
apiKey => the api-key
apiSecret => the api-secret
campaignId => the default campaign id
pgpSecret => the pgp private key
pgpPassword => the password for your pgp key
Config instance
Browser
const config = new XcooBee.sdk.Config(options);
NodeJS
1. Via constructor
const config = new XcooBee.Config(options);
2. Via utility from file
const config = await XcooBee.ConfigUtils.createFromFile();
The createFromFile
function will search for a XcooBee config file in the user's home directory.
The files will be located inside your home
directory in the .xcoobee
subdirectory. Thus the full path to config are:
/[home]/.xcoobee/config
=> the configuration options
/[home]/.xcoobee/pgp.secret
=> the pgp secret key in separate file
on Windows it is in the root of your user directory
/Users/MyUserDir/.xcoobee/config
=> the configuration option
/Users/MyUserDir/.xcoobee/pgp.secret
=> the pgp secret key in separate file
The initial content of the config file is plain text, with each option on a separate line.
example file:
apiKey=8sihfsd89f7
apiSecret=8937438hf
campaignId=ifddb4cd9-d6ea-4005-9c7a-aeb104bc30be
pgpPassword=somethingsecret
SDK instance
Passing a Reference to SDK Instance
The config instance can be set on an SDK instance by passing it to the
Sdk
constructor or it can be set post construction with the
Sdk#config
setter.
Browser
const sdk = new XcooBee.sdk.Sdk(config);
NodeJS
const sdk = new XcooBee.Sdk(config);
Set after Sdk construction.
sdk.config = config;
Then a call to an SDK function will not need to be passed a reference to a
config instance. For example, calling bees.listBees
can be as simple as
const bees = await sdk.bees.listBees('social');
Passing a Reference with Each Function Call
All SDK functions accept an optional reference to a config instance as the last argument. When passed as the last argument, then any config instance passed to the SDK instance will be ignored.
The following demonstrates passing a config instance to bees.listBees
.
const bees = await sdk.bees.listBees('social', config);
Note: The config passed to an SDK function is not merged with the config passed to the SDK instance.
Tests
Running Unit Tests
You can use the following command line to run unit test to validate the project
npm run test:unit
Running Integration Tests
When your initial developer account is created it will be populated with data so that you can test the project against actual data and system.
You will have to configure your __tests__\integration\.env.local
file prior to running the integration tests.
You can use a command line to run the integration tests for this project. You will need to clone the repo from GitHub and run the following command line:
npm run test:integration