Package Exports

rokka

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (rokka) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

rokka.js

JavaScript client library for rokka.

rokka.js runs on node as well as within the supported browsers. To use in a browser, either use a script tag using https://unpkg.com/rokka or import it using the ES6 module syntax:

import rokka from 'rokka'

Install

$ npm install rokka --save
# If using on the server side, babel-runtime is required to run it:
$ npm install babel-runtime --save

Usage

const rokka = require('rokka')({
  apiKey: 'apikey'
});

rokka.sourceimages.list('myorg')
  .then(function(result) {
    console.log(result);
  })
  .catch(function(err) {
    console.error(err);
  });

Documentation

Initializing the rokka client.

const rokka = require('rokka')({
  apiKey: 'apikey',       // required for certain operations
  apiHost: '<url>',       // default: https://api.rokka.io
  apiVersion: <number>,   // default: 1
  renderHost: '<url>',    // default: https://{organization}.rokka.io
  debug: true,            // default: false
  transport: {
    requestTimeout: <number>,  // milliseconds to wait for rokka server response (default: 30000)
    retries: <number>,         // number of retries when API response is 429 (default: 10)
    minTimeout: <number>,      // minimum milliseconds between retries (default: 1000)
    maxTimeout: <number>,      // maximum milliseconds between retries (default: 10000)
    randomize: <boolean>       // randomize time between retries (default: true)
  }
});

All properties are optional since certain calls don't require credentials.

Users

rokka.users.create(email, [organization) → Promise

rokka.users.create('user@example.org')
  .then(function(result) {})
  .catch(function(err) {});

rokka.users.getId() → Promise

Get user_id for current user

rokka.users.getId()
  .then(function(result) {})
  .catch(function(err) {});

Billing

rokka.billing.get(organization, [from=null], [to=null]) → Promise

Retrieve statistics about the billing of an organization

If from and to are not specified, the API will return data for the last 30 days.

rokka.billing.get('myorg', '2017-01-01', '2017-01-31')
  .then(function(result) {})
  .catch(function(err) {});

Organizations

rokka.organizations.get(name) → Promise

Get a list of organizations.

rokka.organizations.get('myorg')
  .then(function(result) {})
  .catch(function(err) {});

rokka.organizations.create(name, billingEmail, displayName) → Promise

Create an organization.

rokka.organizations.create('myorg', 'billing@example.org', 'Organization Inc.')
  .then(function(result) {})
  .catch(function(err) {});

Memberships

Roles

rokka.memberships.ROLES.READ - read-only access
rokka.memberships.ROLES.WRITE - read-write access
rokka.memberships.ROLES.UPLOAD - upload-only access
rokka.memberships.ROLES.ADMIN - administrative access

rokka.memberships.create(organization, userId, roles) → Promise

Add a member to an organization.

rokka.memberships.create('myorg', '613547f8-e26d-48f6-8a6a-552c18b1a290', [rokka.memberships.ROLES.WRITE])
  .then(function(result) {})
  .catch(function(err) {});

rokka.memberships.delete(organization, userId) → Promise

Delete a member in an organization.

rokka.memberships.delete('myorg', '613547f8-e26d-48f6-8a6a-552c18b1a290')
  .then(function(result) {})
  .catch(function(err) {});

rokka.memberships.createWithNewUser(organization, roles) → Promise

Create a user and membership associated to this organization.

rokka.memberships.createWithNewUser('myorg', [rokka.memberships.ROLES.READ])
  .then(function(result) {})
  .catch(function(err) {});

rokka.memberships.list(organization) → Promise

Lists members in an organization.

rokka.memberships.list('myorg')
  .then(function(result) {})
  .catch(function(err) {});

rokka.memberships.get(organization, userId) → Promise

Get info of a member in an organization.

rokka.memberships.get('myorg',userId)
  .then(function(result) {})
  .catch(function(err) {});

Source Images

rokka.sourceimages.list(organization, params) → Promise

Get a list of source images.

By default, listing sourceimages sorts them by created date descending.

rokka.sourceimages.list('myorg')
  .then(function(result) {})
  .catch(function(err) {});

Searching for images can be achieved using the search parameter. Supported are predefined fields like height, name etc. but also user metadata. If you search for user metadata, the field name has to be prefixed with user:TYPE. All fields are combined with an AND. OR/NOT is not possible.

Example:

const search = {
  'user:int:id': '42',
  'height': '64'
}
rokka.sourceimages.list('myorg', { search: search })
  .then(function(result) {})
  .catch(function(err) {});

The search also supports range and wildcard queries. Check out the rokka documentation for more.

Sorting works with user metadata as well and can be passed as either an array or as a comma separated string.

rokka.sourceimages.get(organization, hash, queryParams) → Promise

Get information of a source image by hash.

rokka.sourceimages.get('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a')
  .then(function(result) {})
  .catch(function(err) {});

rokka.sourceimages.getWithBinaryHash(organization, binaryHash) → Promise

Get information of a source image by its binary hash.

rokka.sourceimages.getWithBinaryHash('myorg', 'b23e17047329b417d3902dc1a5a7e158a3ee822a')
  .then(function(result) {})
  .catch(function(err) {});

rokka.sourceimages.download(organization, hash) → Promise

Download image by hash.

rokka.sourceimages.download('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a')
  .then(function(result) {})
  .catch(function(err) {});

rokka.sourceimages.autolabel(organization, hash) → Promise

Autolabels an image.

You need to be a paying customer to be able to use this.

rokka.sourceimages.autolabel('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a')
  .then(function(result) {})
  .catch(function(err) {});

rokka.sourceimages.create(organization, fileName, binaryData, [metadata=null], [options={}]) → Promise

Upload an image.

const file = require('fs').createReadStream('picture.png');
rokka.sourceimages.create('myorg', 'picture.png', file)
  .then(function(result) {})
  .catch(function(err) {});

With directly adding metadata:

rokka.sourceimages.create('myorg', 'picture.png', file, {'meta_user': {'foo': 'bar'}})

rokka.sourceimages.createByUrl(organization, url, [metadata=null], [options={}]) → Promise

Upload an image by url.

rokka.sourceimages.createByUrl('myorg', 'https://rokka.rokka.io/dynamic/f4d3f334ba90d2b4b00e82953fe0bf93e7ad9912.png')
  .then(function(result) {})
  .catch(function(err) {});

With directly adding metadata:

rokka.sourceimages.createByUrl('myorg',  'https://rokka.rokka.io/dynamic/f4d3f334ba90d2b4b00e82953fe0bf93e7ad9912.png', {'meta_user': {'foo': 'bar'}})

rokka.sourceimages.delete(organization, hash) → Promise

Delete image by hash.

rokka.sourceimages.delete('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a')
  .then(function(result) {})
  .catch(function(err) {});

rokka.sourceimages.deleteWithBinaryHash(organization, binaryHash) → Promise

Delete source images by its binary hash.

rokka.sourceimages.deleteWithBinaryHash('myorg', 'b23e17047329b417d3902dc1a5a7e158a3ee822a')
  .then(function(result) {})
  .catch(function(err) {});

rokka.sourceimages.restore(organization, hash) → Promise

Restore image by hash.

rokka.sourceimages.restore('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a')
  .then(function(result) {})
  .catch(function(err) {});

rokka.sourceimages.copy(organization, hash, destinationOrganization, [overwrite=true]) → Promise

Copy image by hash to another org.

rokka.sourceimages.copy('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a', 'anotherorg', true)
  .then(function(result) {})
  .catch(function(err) {});

Dynamic metadata

See the dynamic metadata documentation for more information.

rokka.sourceimages.setSubjectArea(organization, hash, coords, [options={}]) → Promise

Set the subject area of a source image.

The subject area of an image is used when applying the crop operation with the auto anchor to center the cropping box around the subject area.

rokka.sourceimages.setSubjectArea('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a', {
  x: 100,
  y: 100,
  width: 50,
  height: 50
},
{
  deletePrevious: false
}).then(function(result) {})
  .catch(function(err) {});

rokka.sourceimages.removeSubjectArea(organization, hash, [options={}]) → Promise

Removes the subject area from a source image.

rokka.sourceimages.removeSubjectArea('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a')
  .then(function(result) {})
  .catch(function(err) {});

User metadata

See the user metadata documentation for more information.

rokka.sourceimages.meta(organization, hash, data) → Promise

Add user metadata to a source image.

See the user metadata documentation for an explanation.

rokka.sourceimages.meta.add('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a', {
  somefield: 'somevalue',
  'int:some_number': 0,
  'delete_this': null
}).then(function(result) {})
  .catch(function(err) {});

rokka.sourceimages.replace(organization, hash, data) → Promise

Replace user metadata of a source image with the passed data.

See the user metadata documentation for an explanation.

rokka.sourceimages.meta.replace('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a', {
  somefield: 'somevalue',
  'int:some_number': 0
}).then(function(result) {})
  .catch(function(err) {});

rokka.sourceimages.delete(organization, hash, [field=null]) → Promise

Replace user metadata of a source image with the passed data.

See the user metadata documentation for an explanation.

rokka.sourceimages.meta.delete('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a')
  .then(function(result) {})
  .catch(function(err) {});

If the third parameter (field) is specified, it will just delete this field.

Operations

Available operations

rokka.operations.resize(width, height, options = {})
rokka.operations.autorotate(options = {})
rokka.operations.rotate(angle, options = {})
rokka.operations.dropshadow(options = {})
rokka.operations.trim(options = {})
rokka.operations.crop(width, height, options = {})
rokka.operations.noop()
rokka.operations.composition(width, height, mode, options = {})
rokka.operations.blur(sigma, radius)

Please refer to the rokka API documentation

rokka.operations.list() → Promise

Get a list of available stack operations.

rokka.operations.list()
  .then(function(result) {})
  .catch(function(err) {});

Stack options

rokka.stackoptions.get() → Promise

Returns a json-schema like definition of options which can be set on a stack.

rokka.stackoptions.get()
  .then(function(result) {})
  .catch(function(err) {});

Stacks

rokka.stacks.list(organization, [limit=null], [offset=null]) → Promise

Get a list of available stacks.

rokka.stacks.list('myorg')
  .then(function(result) {})
  .catch(function(err) {});

rokka.stacks.get(organization, name) → Promise

Get details about a stack.

rokka.stacks.get('myorg', 'mystack')
  .then(function(result) {})
  .catch(function(result) {});

rokka.stacks.create(organization, name, stackConfig, [params={}]) → Promise

Create a new stack.

The signature of this method changed in 0.27.

Using a single stack operation object (without an enclosing array) as the 3rd parameter (stackConfig) is since version 0.27.0 not supported anymore.

const operations = [
  rokka.operations.rotate(45),
  rokka.operations.resize(100, 100)
]

// stack options are optional
const options = {
  'jpg.quality': 80,
  'webp.quality': 80
}

// stack expressions are optional
const expressions = [
  rokka.expressions.default('options.dpr > 2', { 'jpg.quality': 60, 'webp.quality': 60 })
]

// query params are optional
var queryParams = { overwrite: true }
rokka.stacks.create(
  'test',
  'mystack',
  { operations, options, expressions },
  queryParams
).then(function(result) {})
 .catch(function(err) {})

rokka.stacks.delete(organization, name) → Promise

Delete a stack.

rokka.stacks.delete('myorg', 'mystack')
  .then(function(result) {})
  .catch(function(err) {});

Render

rokka.render.getUrl(organization, hash, format, [mixed]) → string

Get URL for rendering an image.

rokka.render.getUrl('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a', 'png', 'mystack')

Stats

rokka.stats.get(organization, [from=null], [to=null]) → Promise

Retrieve statistics about an organization.

If from and to are not specified, the API will return data for the last 30 days.

rokka.stats.get('myorg', '2017-01-01', '2017-01-31')
  .then(function(result) {})
  .catch(function(err) {});