byte-sdk v0.0.12
byte-sdk
Simple model for writing Byte computers.
Computers appear in the Byte client and can provide an extended feature set for the user. Writing a new computer can be quite easy:
var app = require(‘koa’)();
var router = require(‘koa-router’);
var ByteSDK = require(‘byte-sdk’);
var btcaverage = require(‘btcaverage’);
var routes = new router();
app.use(routes.routes());
app.use(routes.allowedMethods());
routes.get(‘/bitcoin’, function* () {
var response = new ByteSDK.ComputerResponse();
var priceDetails = yield btcaverage();
response.addObject(new ByteSDK.TextObject({
‘text’: ‘$’ + parseFloat(priceDetails.average).toFixed(2)
}));
this.body = response;
});
app.listen(3000);
Look in examples/computers
for some more complete examples.
Contents
- What is a Computer?
- Types of Computers
- ComputerResponse Object Specs
- Error Handling
- Testing
- Shipping a Computer
- Registering a Computer
What is a Computer?
Simply put, a Byte Computer is a minimal web–app that returns a ComputerResponse()
object containing at least one Object
(currently: Paragraph, Text, Link, Image, Graphic, Gif, Video, or Music).
Types of Computers
There are two types of computers: those that require config and those that do not.
No Config
If the computer returns a response without any config (e.g., Bitcoin), you only need to define a GET
route (to return the results):
routes.get(‘/bitcoin’, function* () {
var response = new ByteSDK.ComputerResponse();
…
this.body = response;
});
Config
If the computer requires input/config to return a result (e.g., Image Search), you must define both a GET
route (to return the config params) and a POST
route (to return the results):
routes.get(‘/images’, function* () {
this.body = new ByteSDK.ComputerConfig(‘query’, ‘kittens’);
});
routes.post(‘/images’, bodyParser, function* () {
var query = this.request.body.data.query;
var response = new ByteSDK.ComputerResponse();
…
this.body = response;
});
ComputerConfig Object Specs
To create a computer config object, return new ByteSDK.ComputerConfig(name, placeholder)
where:
name
is the label for the object (you’ll use this to access the config response in yourPOST
handler)placeholder
is a string that is displayed to the user as an example input (e.g., ‘Dora the Explorer’)
ComputerResponse Object Specs
To create a computer config object, call new ByteSDK.ComputerResponse()
. To add an object to the computer response, call response.addObject(object)
where object
is a response object.
There are currently eight types of response objects: ParagraphObject
, TextObject
, LinkObject
, ImageObject
, GraphicObject
, GifObject
, VideoObject
, and MusicObject
. These are simple to create: new ByteSDK.ParagraphObject({})
.
The parameters for these response objects are documented in the BFF documentation.
Error Handling
If you encounter an error at any point, simply return a 400
or a 500
to the client. The client will then inform the user that an error occurred and will prompt them to try again.
Testing
At the very least, you should use curl
to test your computer locally before shipping. For example:
curl -X GET -H “Accept:application/json” http://localhost:3000/kanye
curl -X POST -H “Accept:application/json” -H “Content-Type:application/json” http://localhost:3000/gifs -d ‘{“data”: {“query”: “cat”}}’
Broken computers will be removed from the app automatically on a regular basis.
Shipping a Computer
We currently only support self–hosting for custom computers. Since computers are simple web–apps (and since you’re using this library, it’s probably a node.js app), there are countless options for hosting your computer. These include:
However, we do have a mechanism for hosting basic computers (those that return a simple set of images without any logic). Head over to developers.byte.co to get started.
Registering a Computer
Once you have finished developing your computer, you need to register it for it to show up in the Byte app. To get started, head to developers.byte.co and sign in with your Byte account.
Once registered, your computer will immediately be searchable within the app. You should check and see if it works as intended.
Approval Process
There is no formal approval process. However, we automatically run a check to make sure your endpoint is live and functional when you register the computer.
Byte reserves the right to disable any computers that do not work properly, as well as any computers that serve illegal/infringing content.