smartoptim v1.0.0

Official SmartOptim.com library for Node.js

This is official node.js client for working with the SmartOptim.com API.

The library implements the SmartOptim REST service for optimizing images. The library can be used in any project by installing with npm command.

Installation

npm install smartoptim --save

Getting Started

To start using the SmartOptim Image Optimization service you will need to obtain API key from SmartOptim.com. Once you have the key you will be able to start using the service immediately.

How to use

You can optimize your images in several ways. The api supports any of those: single url, single local file path, multiple urls, multiple local file paths.

Using the url/s approach is great for images that are already in production or any other place on the Internet. The direct upload method is ideal for your own galleries that aren't public, your deployment process, build script or the on-the-fly processing of your user's uploads where you don't have the images available online yet.

If you provide url/urls this library will pass them to the API server and the API server will download the contents. If you provide local path/paths the library will upload them in the initial request using HTTP Post.

The API currently accepts the following parameters:

NOTE: If max_height and max_width are specified the image will be resized to the bigger one of them keeping the ratio.

Lossy Optimization

When you decide to sacrifice just a small amount of image quality (usually unnoticeable to the human eye), you will be able to save up to 90% of the initial file weight. Lossy optimization will give you outstanding results with just a fraction of image quality loss.

Optimization / Fetching results

SmartOptim gives you with two ways to obtain the results of the optimization as follows:

• Call https://api.smartoptim.com/optimize/{process_id}/result?timeout=300 endpoint and wait for the result for the specified timeout.
• Provide callback_url parameter in your initial request and our servers will send the response to the callback by using HTTP POST.

1.) Using /result endpoint

In the following example 65bfc090-a2fc-11e8-ab19-ad2bb706c7e4 is unique process_id returned in the initial call. Using it you can query the results. Note that the process_id is unique for every request you send.

Request

Method POST, URL: https://api.smartoptim.com/v1/optimize

{
    type: 'url',
    url: 'https://someurl.com/1.jpg',
    compression: 'lossy'
}

Response

{
    "status": "processing",
    "code": 202,
    "process_id": "65bfc090-a2fc-11e8-ab19-ad2bb706c7e4"
}

So now we have the process_id. We are one step closer to the results and you should send another request to obtain the result as follows:

Request

Method POST, URL: https://api.smartoptim.com/v1/optimize/65bfc090-a2fc-11e8-ab19-ad2bb706c7e4/result?timeout=300

Response

{
    "status": "ok",
    "code": 200,
    "result": [
        {
            "file_name": "1.jpg",
            "original_size": 315615,
            "optimized_size": 127380,
            "saved_bytes": 188235,
            "saved_percent": 60,
            "url": "https://srv1.smartoptim.test/b12020cdf3a1/xmdobhRRl7tk6xd.png",
            "success": 1
        }
    ],
    "user": {
        "name": "John Doe",
        "email": "john@doe.com",
        "tokens": 474
    }
}

The timeout property is used to specify how much seconds to wait for the job to finish. Assuming that we specified timeout to be 120, if the job finishes in less than 120 seconds then it will return the results of the job, otherwise the status of the response will stil be processing.

2.) Fetch: Using callback_url parameter

To receive the results using callback_url you should provide it in the initial POST call. Specify the callback_url with your url. Make sure you have the callback method implemented otherwise you will not be able to receive/process the results.

Request

Method POST, URL: https://api.smartoptim.com/v1/optimize

{
    type: 'url',
    url: 'https://someurl.com/1.jpg',
    compression: 'lossy',
    callback_url: 'https://my-awesome-website.com/smartoptim_callback'
}

Response

{
    "status": "processing",
    "code": 202,
    "process_id": "65bfc090-a2fc-11e8-ab19-ad2bb706c7e4"
}

Results posted to the Callback URL

{
    "status": "ok",
    "code": 200,
    "id": "65bfc090-a2fc-11e8-ab19-ad2bb706c7e4",
    "result": [
        {
            "file_name": "1.jpg",
            "original_size": 315615,
            "optimized_size": 127380,
            "saved_bytes": 188235,
            "saved_percent": 60,
            "url": "https://srv1.smartoptim.test/b12020cdf3a1/xmdobhRRl7tk6xd.png",
            "success": 1
        }
    ],
    "user": {
        "name": "John Doe",
        "email": "john@doe.com",
        "tokens": 474
    }
}

NOTE: The callback_url must be public and accessible by our servers. If by any reason our server fail to access it you can always query the result with using the /result endpoint described above.

Usage

This library provides easy to use interface to utilize the SmartOptim API. In the following example we import smartoptim, make instance of the SmartOptim and then we call the optimize method.

The optimize method accepts 3 parameters and all are mandatory

• resource (string|array) - This can be local path or array that contains local paths, or url or array that contains urls. The array can be max up to 5 urls/paths.
• params (dict) - This object contains the API parameters in key:value based representation.
• timeout (integer) - This is the timeout to wait once the api request is sent. By default it is ignored if you provide callback_url in the params.
• callback (function) - This is where you receive the results.

NOTE: If you provide multiple images as array they either need to be all local paths or public urls. You can not mix those!

var SmartOptim = require('smartoptim');

var client = new SmartOptim({
    api_key: '_YOUR API KEY_'
});

var source = 'https://awesome-website/image.jpg';

client.optimize(source, {}, 300, function (response) {
    if (response.status === 'processing') {
        // Still processing.
        // If callback_url has been passed the status will be processing
        // So you should handle the processing in your callback url.
    } else if (response.status === 'ok') {
        // Processing finished!
        // Results are there
        for (var i in response.result) {
            if (response.result.hasOwnProperty(i)) {
                console.log('Total saved: ' + response.result[i].saved_percent + '%');
                console.log('Download url: ' + response.result[i].url)
            }
        }
    } else if (response.status === 'error') {
        // If error happened you have an errors array with all the errors.
        for (var i in response.errors) {
            if (response.errors.hasOwnProperty(i)) {
                // Print errors or do something!
                console.log(response.errors[i])
            }
        }
    } else {
        // Unexpected error
    }
});

Depending on a choosen response option (Call /result endpoint or Callback URL) in the data object you will find either the optimization ID or optimization results containing a status property, file name, original file size, optimized file size, amount of savings and array of objects that contain optimized image URL:

{
    "status": "ok",
    "code": 200,
    "result": [
        {
            "file_name": "1.png",
            "original_size": 315615,
            "optimized_size": 127380,
            "saved_bytes": 188235,
            "saved_percent": 60,
            "url": "https://srv1.smartoptim.test/b12020cdf3a1/xmdobhRRl7tk6xd.png",
            "success": 1
        },
        {
            "file_name": "2.png",
            "original_size": 3257509,
            "optimized_size": 1123807,
            "saved_bytes": 2133702,
            "saved_percent": 66,
            "url": "https://srv1.smartoptim.test/b12020cdf3a1/EYLp7KxBfgGt0Ly.png",
            "success": 1
        }
    ],
    "user": {
        "name": "John Doe",
        "email": "john@doe.com",
        "tokens": 1234
    }
}

For more examples please see the examples/ directory.

Contribution

Feel free to open pull request if you noticed any bug o want to propose improvement.

Support

If you have any questions feel free to contact us at support@smartoptim.com

License

MIT License

Copyright (c) 2018 IDEOLOGIX MEDIA (https://ideologix.com)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.