Vazco Services SDK

SDK for Vazco Services.

On this page:

1. Abstract frame of client service
2. Basic usage
   2.1. On server side
   2.2. On client side
3. Services
   3.1. Render
   3.2. Files
   3.3. Recording
   3.4. Hello
4. Linting
5. Testing
6. ES2015 Setup
7. About AWS Regions

Abstract frame of client service

See abstract-services-sdk.

Basic usage

On server side:

import VazcoServicesSDK from 'vazco-services-sdk';

const vazcoSDK = new VazcoServicesSDK({
    url: 'http://some.url/service',
    appId: '41h0ft5u96350u4j112q9lxtyappa736', // a unique identifier of Vazco Services backend (services app)
    "publicKeyString": "-----BEGIN PUBLIC KEY-----\nAFwwDQRJKo.....kCAwEAAZ==\n-----END PUBLIC KEY-----",
    "adminKey": "ksp2SGu98jaToW45Mr-0-PLjhwB2Q4Cb",
});

// getting a token that will be needed on the client side later
const token = vazcoSDK.generateTicket({userId = '', groupId = '', sessionId = '', hash = '', ttl = 86400});

On client side

import VazcoServicesSDK from 'vazco-services-sdk';
import {getFileUrl} from 'vazco-services-sdk/dist/helpers';

const vazcoSDK = new VazcoServicesSDK({
    url: 'http://some.url/service',
    appId: '41h0ft5u96350u4j112q9lxtyappa736'
});

// setting a getter for the ticket token generated on the server side (can be returned by a Promise)
vazcoSDK.onGetTicket(() => <tokenFromServer>); // callback should return a Promise or a ticket

async function renderPdf (url = 'https://website-to-take-a-screenshot.com') {
    // an example of getting a PDF service
    const render = await vazcoSDK.getService('render');
    const info = render.renderFile({url});
    console.log(info);
    return getFileUrl(info);
}

renderPdf('https://website-to-take-a-screenshot.com').then(url => console.log('url to pdf:', url), err => console.error(err););

Services

You can get an access to an instance of a particular service by calling .getService on an instance of the SDK. The result of .getService is a Promise with an instance of a service which name is passed as the first argument.

Example:

let renderFile;
vazcoSdk.getService('renderFile').then(service => renderFile = service);

Render

The service renders a web page under URL as a PDF or image file using Firefox. It means you can also use JavaScript or canvas to print visual charts.

• render.renderFile({url, fileType, orgName, paperSize, onlyViewport, width, height, engine, delay, debug})
  Renders an image of a website and returns an object describing the file saved in the backend (as a JSON).
  Settings:
  • url: the URL of the website whose image you want to render
  • fileType: one of 'jpg', 'jpeg', 'png', 'bmp', 'pdf' (default: 'pdf')
  • orgName: name of generated file, without extension (default: 'file')
  • paperSize: paper settings object (only for PDF):
    • margin: margin size - number (pixels), number with unit (string) or an object specyfying particular margins such as 'top', 'left', etc. (default: '1cm')
    • format: paper format, one of standard formats such as 'A3', 'A4', 'A5', 'Legal', 'Letter', 'Tabloid' (default: 'A4')
    • orientation: one of 'landscape', 'portrait', if not provided depends on width and height (see below, default: 'portrait') For more detailed information about paperSize settings please view appropriate section in SlimerJS documentation. Note that render service uses only aforementioned paperSize's properties.
  • onlyViewport: boolean value, only for file types: 'jpg', 'jpeg', 'png', 'bmp' (default: false)
  • width: the width of the virtual window in pixels, a number between 100 and 2000 (default: 794)
  • height: the height of the virtual window in pixels, a number between 100 and 2000 (default: 1123)
  • engine: one of 'gecko', 'wkhtml' (default: 'gecko')
  • delay: time in milliseconds to wait before the conversion (default: 1000)
  • timeout: post timeout in milliseconds (default: 30 000)
  • debug: debug mode, boolean value
• render.remove(pathInStorage)
  Removes the file from the backend.
• render.disable(pathInStorage)
  Shuts off the web access to the file. Depends on the storage backend configuration so you should be sure the configuration of the backend is correct.
• render.enable(pathInStorage)
  Restores the web access to the file in the backend.

You can obtain the file path by accessing path property in the file object returned by renderFile action.

Files

This service helps you with uploading files to a web-accessible location like S3 or file system based backend. It can also resize, crop and auto-rotate uploaded images.

Parent directories are created automatically as needed (like in S3).
Files are by default marked as readable via the web (like a filesystem + web server).
Images can be automatically scaled to multiple sizes (defined via server GUI).
Non-image files are also supported.
Web access to files can be disabled and re-enabled (if the backend gives that possibility).

• files.upload(file, params = {})
  Uploads a binary file as a multipart of data and returns an object describing the file saved in the backend (as a JSON).
  Arguments:
  • file: a file object
  • params: name of the file (string) or additional settings object:
    • name: name of the file (default: 'file')
    • isImage: determines if the file is an image (boolean value) - in this case image support set in the backend like scaling will be launched (default: false)
    • timeout: post timeout in milliseconds (default: 30 000)
    • onProgress: custom function
    • token: optional - manually passed token
• files.remove(pathInStorage)
  Removes the file from the backend.
• files.disable(pathInStorage)
  Shuts off the web access to the file. Depends on the storage backend configuration so you should be sure the configuration of the backend is correct.
• files.enable(pathInStorage)
  Restores the web access to the file in the backend.
• files.getConfiguration()
  Returns server app configuration object (as a JSON): {backend, maxFileSizeKB, acceptFileTypes, imageSizes}.

You can obtain the file path by accessing path property in the file object returned by upload action.

Recording

The service helps with recording audio or video media via user's browser and uploading it to the backend.

• recording.start({audio, video})
  Starts recording media of selected type using the browser (asks for user permission if needed). Returns a Promise with a handler object: {isStopped, status, pause, resume, stop}.
  stop returns a Promise from which you can get the recorded file (result): {result}.
  Settings:
  • audio: stream media of type audio, boolean value (default: true)
  • video: stream media of type video, boolean value (default: false); warning: not implemented yet!
• recording.upload(file, params = {})
  Uploads recorded file as a multipart of data (see how to get the file under recording.start above) and returns an object describing the file saved in the backend (as a JSON).
  Arguments:
  • file: the file object
  • params: name of the file (string) or additional settings object:
    • name: name of the file (default: 'media')
    • onProgress: custom function
    • token: optional - manually passed token
• recording.remove(pathInStorage)
  Removes the file from the backend.
• recording.disable(pathInStorage)
  Shuts off the web access to the file. Depends on the storage backend configuration so you should be sure the configuration of the backend is correct.
• recording.enable(pathInStorage)
  Restores the web access to the file in the backend.
• recording.on(eventName, func)
  • eventName: event name like 'audioprocess', 'statechange', 'updateStatus'
  • func: callback
• recording.off(eventName, func)
  • eventName: event name like 'audioprocess', 'statechange', 'updateStatus'
  • func: callback
• recording.once(eventName, func)
  • eventName: event name like 'audioprocess', 'statechange', 'updateStatus'
  • func: callback
• recording.getConfiguration()
  Returns server app configuration object (as a JSON): {backend, maxFileSizeKB, acceptFileTypes, imageSizes}.

You can obtain the file path by accessing path property in the file object.

Hello

You can use this simple exemplary service to test integration between SDK and Vazco Services. It provides an API endpoint that returns {greeting: 'Hello You'}.

• hello.getHello(token)
  Returns {greeting: 'Hello You'} object.
  • token: optional - manually passed token
• hello.getError(token)
  Gets error 406.
  • token: optional - manually passed token

Linting

• ESLint support is added to the project.
• It is configured for ES2015 and configurations inherited from graphql/graphql-js.
• Use npm run lint to lint your code and npm run lintfix to fix common issues.

Testing

• You can write tests under __test__ directory anywhere inside lib including its subdirectories.
• Then run npm test to test your code. (It will lint the code as well).
• You can also run npm run testonly to run the tests without linting.

ES2015 Setup

• ES2015 support is added with Babel 6.
• After you publish your project to npm it can be run on older Node.js versions and browsers without the support of Babel.
• This project uses ES2015 and some of the upcoming features like async await.
• You can change them by adding and removing presets.
• All your custom polyfills will be taken from local babel-runtime package. This package does not add any global polyfills and pollute the global namespace.

About AWS Regions

For your convenience when using buckets in a region other than the US Standard you can specify the region option. When you do so the endpoint is automatically assembled.

As of this writing, valid values for the region option are:

• US Standard (default): us-standard,
• US West (Oregon): us-west-2,
• US West (Northern California): us-west-1,
• EU (Ireland): eu-west-1,
• Asia Pacific (Singapore): ap-southeast-1,
• Asia Pacific (Tokyo): ap-northeast-1,
• South America (Sao Paulo): sa-east-1.

If new regions are added later, their subdomain names will also work when passed as the region option. See the AWS Endpoint documentation for the latest list.

Convenience APIs such as putFile and putStream currently do not work as expected with buckets in regions other than US Standard without explicitly specify the region option. This will eventually be addressed by resolving issue #66; however, for performance reasons, it is always best to specify the region option anyway.