xcoobee-js-sdk

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 can be signed using PGP protocols with the proper configuration. The data packets that you will receive are signed with your public key and the packages that you send are signed with your private key. TODO: I don't believe any communication is encrypted with the private 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 available on our documentation site.

call limits

If you are using developer accounts, please be aware that there is a call limit. This is normally 120 calls per hour or 600 calls per 24 hour period.

For subscription accounts your call limits are determined per your account and contract. If you hit your call limits, you will need to contact your account manager or support to increase them.

Once you have exceeded your call limits, your call will return status 429 too many requests.

logs

API calls are logged like standard transactions with the same time to live constraints.

About PGP Secret and password

All PGP data is optional to the configuration object. If you do not supply it, then the SDK will skip decryption/encryption steps. You will have to do these outside the SDK and supply or process the data yourself.

TODO: We are not doing anything with the PGP configuration information. => please see PHP SDK on the flow for decryptiong/encryption

TODO: How would one do the decryption/encryption steps outside of the SDK? => Any developer wishing to bypass the encryption/decryption feature will need to implement their own encryption/decryption routines outside the SDK. They can do so in any manner they chose.

Asynchronous

Because JavaScript is not multi-threaded, almost all function calls in the SDK are asynchronous (i.e., non-blocking). Each asynchronous function returns a Promise. This allows the use of async/await syntax in JS environments that support it. Being asynchronous allows the SDK to be embedded, for example in an Express app, and not block the app for each call to the SDK. The Promise may be resolved with a Response instance or rejected with an ErrorResponse instance.

Getting Started

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.

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.

Constructor

import XcooBee from '@xcoobee/sdk-js';

const config = new XcooBee.sdk.Config({
  apiKey: 'YourApiKey',
  apiSecret: 'YourApiSecret',
  apiUrlRoot: 'https://api.xcoobee.net',
  campaignId: 'TheIdOfOneOfYourCampaigns',
});

Utility Function

import XcooBee from '@xcoobee/sdk-js';

XcooBee.sdk.ConfigUtils.createFromFile()
  .then(config => {
    ...
  })
  .catch(err => console.error(err));

The createFromFile function will search for a XcooBee config file in the user's home directory. See the API docs for details.

Regardless of which way you choose to instantiate a config instance, it needs to be made available to the SDK functions. One way is to let the SDK transparently handle it by passing the SDK instance a reference. The other way is to pass a reference to each SDK function call.

Passing a Reference to SDK Instance

The config instance can be set on an SDK instance by passing it to the XcooBee.sdk.Sdk constructor or it can be set post construction with the Sdk#config setter.

// Set config during Sdk construction.
const sdk = XcooBee.sdk.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

sdk.bees.listBees('social').then(...);

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.

sdk.bees.listBees('social', null, null, config).then(...);

Note: The config passed to an SDK function is not merged with the config passed to the SDK instance.

Responses

All calls to the SDK functions return a Promise which will either resolve with a successful response or reject with an error response. An error response means that the call did not complete successfully and no processing operation has begun. A successful response, on the other hand, means that the call completed successfully but it does not necessarily mean that the processing operation initiated by the call has also completed. It all depends on the particular SDK function being called. For example, when the bees.listBees function resolves with a successful response, the processing operation (in this case, searching for a list of bees matching a search string) has completed and the result is apart of the response. However, when the consents.requestConsent function resolves with a successful response, the processing operation has just begun. The actual response to the requesting consent is asynchronous. The actual response will be POSTed to the webhook after the processing operation has completed. Which of the SDK functions result in a webhook being called is documented in the API docs.

Events

The XcooBee system also communicates via events. It does so using the webhook paradigm (HTTP Post).

Using Events When Your System is Behind a Firewall

There are specific polling functions available to you to retrieve data generated by events directly. The XcooBee SDK has implemented the getEvents() function call for this purpose.

The Poller Application

For convenience we have built a Single Page Application (SPA) that can be used to bridge the event webhook system to your local application while it is in development.

If your application is under development and you need to work with events you can use the poller program. The poller program is a single page application that you can access from the poller directory of the repo. We recommend that you copy the contents to a local webserver. It acts as bridge to XcooBee events for you. This will allow relay events without the need to publish your website.

SDK Function Call Reference

You can generate an SDK function reference by calling the documentation command npm run build:docs from your terminal. This will generate function call signatures for all exposed functions in the /dist folder.

Tests

Running Unit Tests

You can use the following command line to run unit test to validate the project

TODO: add command lin

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.

TODO: add description for local.env file

You can use the following command line to run the integration tests for this project.

TODO: add command line

More information

You can access more information about our SDK here: https://www.xcoobee.com/docs/developer-documentation/xcoobee-sdk/

General developer documentation can be found here: https://www.xcoobee.com/docs/developer-documentation/