Webtask
Would you like the webtask.io experience in your own SaaS? Try

Documentation

Sandboxjs

The JavaScript SDK for webtask.io

For customized documentation and ready to run samples, please log in.

About

The Auth0 Sandboxjs is a node.js package that allows you to sandbox your code and run it on the public webtask.io cluster. It supports returning Promises and/or invoking node-style callbacks.

Setup

To install sandboxjs open a terminal and run the following:

$ npm install sandboxjs

To start using sandboxjs you have to get a webtask token using wt-cli . If you already use wt-cli use:

$ wt profile ls
If you don't have a profile already, then you have to install wt-cli and initialize a new profile:
$ npm install -g wt-cli
$ wt init
In order to configure a webtask profile you need to provide an email or phone number. You will receive a verification code there which you will have to input to the terminal.

Now that you have a profile setup, let's work on some simple examples.

Create and run a webtask using sandboxjs

The code snippet below creates a new webtask and runs it using Sandbox. The webtask code is defined as module.exports = function (ctx, cb) { cb(null, "hello world"); } and the Sandbox.fromToken method is used to create a Sandbox instance from your webtask token. The token in this example is retrieved from the environment variable WEBTASK_TOKEN. Once the Sandbox instance (profile) is defined, the instance method run is used. This method is a shortcut to create and run a Webtask from the given options. The method's structure is sandbox.run([codeOrUrl], [options], [cb]), where [codeOrUrl] is the code or the URL for the webtask (in our example the code variable holds the webtask code), [options] is the set of options (for example, secrets) used to create the webtask (omitted in our example), and [cb] is the optional callback function for node-style callbacks. In our example the callback function uses Assert to display:

  • the error if the callback returns one
  • The webtask executed as expected if the status code returned by the webtask is 200
  • The webtask returned the expected string if the webtask returns the expected hello world
You can read more on this method here.
var Assert = require('assert');
var Sandbox = require('sandboxjs');

var code = 'module.exports = function (ctx, cb) { cb(null, "hello world"); }';
var profile = Sandbox.fromToken(process.env.WEBTASK_TOKEN);

// This library lets you create a webtask and run it in one step as a shortcut
profile.run(code, function (err, res, body) {
  Assert.ifError(err);
  Assert.equal(res.statusCode, 200, 'The webtask executed as expected');
  Assert.equal(body, 'hello world', 'The webtask returned the expected string');
});

Create a webtask and get the URL

Our second example creates a webtask but instead of running it, returns the URL as output. Making requests to this url will run the specified custom code in a node.js sandbox and will give it access to your secrets in the firstargument of your exported webtask function. In this example we are utilizing the [options] argument and use it to set a secret: auth0: 'rocks'.

var Assert = require('assert');
var Sandbox = require('sandboxjs');

var code = 'module.exports = function (ctx, cb) { cb(null, "hello world"); }';
var profile = Sandbox.fromToken(process.env.WEBTASK_TOKEN);

// This library lets you create a webtask and returns the URL:
profile.create(code, { secrets: { auth0: 'rocks' } }, function (err, webtask) {
  Assert.ifError(err);
  console.log(webtask.url);
});

Update the code of an existing webtask

Our third example retrieves an existing named webtask and updates its code. Let's say that you already have a webtask named my-webtask and it prints Hello world. We will update its code to print Hello there instead. The code snippet uses the method sandbox.updateWebtask(options, [cb]) to update the webtask's code. This function can also be used to update a webtask's secrets or other claims. Note that this method should be used with caution as there is the potential for a race condition where another agent updates the webtask between the time that the webtask details and claims are resolved and when the webtask update is issued.

var Sandbox = require('sandboxjs');

var webtaskName = 'my-webtask'; //existing webtask name
var webtaskCode = 'module.exports = function (ctx, cb) { cb(null, "Hello there"); }'; //updated code
var profile = Sandbox.fromToken(process.env.WEBTASK_TOKEN);

profile.updateWebtask({
  name: webtaskName,
  code: webtaskCode,
});

List of methods

For a list of supported API methods please refer to our GitHub repository.