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)
agent?: <any> // an agent to be used with node-fetch, eg. if you need a proxy (default: undefined)
}
});
All properties are optional since certain calls don't require credentials.
If you need to use a proxy, you can do the following
import { HttpsProxyAgent } from 'https-proxy-agent'
const rokka = require('rokka')({
apiKey: 'apikey'
transport: {agent: new HttpsProxyAgent(proxy)}
});
Users
rokka.users.create(email, [organization) → Promise
Register a new user for the rokka service.
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) {});
User
rokka.user.getId() → Promise
Get user_id for current user
rokka.user.get()
Get user object for current user
rokka.user.listApiKeys()()
List Api Keys of the current user
rokka.user.addApiKey()(comment)
Add Api Key to the current user
rokka.user.deleteApiKey()(id)
Delete Api Key from the current user
rokka.user.getCurrentApiKey()()
Get currently used Api Key
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 accessrokka.memberships.ROLES.WRITE
- read-write accessrokka.memberships.ROLES.UPLOAD
- upload-only accessrokka.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, returns a Stream
rokka.sourceimages.download('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a')
.then(function(result) {})
.catch(function(err) {});
rokka.sourceimages.downloadAsBuffer(organization, hash) → Promise
Download image by hash, returns a Buffer
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) {});
rokka.sourceimages.setProtected(organization, hash, isProtected, [options={}]) → Promise
(Un)sets the protected status of an image.
Important! Returns a different hash, if the protected status changes
rokka.sourceimages.setProtected('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a', true,
{
deletePrevious: false
}).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) {});
rokka.sourceimages.addDynamicMetaData(organization, hash, name, data, [options={}]) → Promise
Add/set dynamic metadata to an image
See the dynamic metadata chapter for details.
rokka.sourceimages.addDynamicMetaData('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a', 'crop_area', {
x: 100,
y: 100,
width: 50,
height: 50
},
{
deletePrevious: false
}).then(function(result) {})
.catch(function(err) {});
rokka.sourceimages.deleteDynamicMetaData(organization, hash, name, [options={}]) → Promise
Delete dynamic metadata of an image
See the dynamic metadata chapter for details.
rokka.sourceimages.addDynamicMetaData('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a', 'crop_area',
{
deletePrevious: false
}).then(function(result) {})
.catch(function(err) {});
rokka.sourceimages.putName(organization, hash, name) → Promise
Change the name of a source image.
rokka.sourceimages.putName('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a', name).then(function(result) {})
.catch(function(err) {});
Source Images
User metadata
See the user metadata documentation for more information.
rokka.sourceimages.meta.add(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.meta.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.meta.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], options) → string
Get URL for rendering an image.
rokka.render.getUrl('myorg', 'c421f4e8cefe0fd3aab22832f51e85bacda0a47a', 'png', 'mystack')
rokka.render.signUrl(url, signKey, [{until:Date = null, roundDateUpTo:number = 300}]) → string
Signs a Rokka URL with an option valid until date.
It also rounds up the date to the next 5 minutes (300 seconds) to improve CDN caching, can be changed
rokka.render.signUrlWithOptions()
Signs a rokka URL with a sign key and optional signature options.
rokka.render.addStackVariables(url, variables, [removeSafeUrlFromQuery=false]) → string
Adds stack variables to a rokka URL in a safe way
Uses the v query parameter, if a variable shouldn't be in the path
rokka.render.getUrlComponents(urlObject) → UrlComponents|false
Get rokka components from an URL object.
Returns false, if it could not parse it as rokka URL.
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) {});
request
rokka.request.request(path, method, body)
Does an authenticated request for any path to the Rokka API