cloudconvert-node

This is a lightweight wrapper for the CloudConvert API.

Feel free to use, improve or modify this wrapper! If you have questions contact us or open an issue on GitHub.

Installation

As usual:

npm install --save cloudconvert

Quickstart

var fs = require('fs');
var cloudconvert = new (require('cloudconvert'))('your_api_key');

fs.createReadStream('tests/input.png')
.pipe(cloudconvert.convert({
    inputformat: 'png',
    outputformat: 'jpg',
    converteroptions: {
        quality : 75,
    }
 }))
.pipe(fs.createWriteStream('out.jpg'))
.on('finish', function() {
    console.log('Done!');
});

You can use the CloudConvert API Console to generate ready-to-use JS code snippets using this wrapper.

The manual way

cloudconvert.convert() creates a Process, start it and waits until it completes. In some cases it might be necessary that you do this steps seperately, as the following example shows:

var fs = require('fs');
var cloudconvert = new (require('cloudconvert'))('your_api_key');

// create the process. see https://cloudconvert.com/apidoc#create
cloudconvert.createProcess({inputformat: 'png', outputformat: 'pdf'}, function(err, conversionProcess) {

    if(err) {
        console.error('CloudConvert Process creation failed: ' + err);
    } else {

        // start the process. see https://cloudconvert.com/apidoc#create
        conversionProcess.start({
            outputformat: 'jpg',
            converteroptions: {
                quality : 75,
            },
            input: 'upload'
        }, function (err, conversionProcess) {

            if (err) {
                console.error('CloudConvert Process start failed: ' + err);
            } else {

                // upload the input file. see https://cloudconvert.com/apidoc#upload
                conversionProcess.upload(fs.createReadStream('tests/input.png'), null, function (err, conversionProcess) {

                    if (err) {
                        console.error('CloudConvert Process upload failed: ' + err);
                    } else {
                        // wait until the process is finished (or completed with an error)
                        conversionProcess.wait(function (err, conversionProcess) {
                            if (err) {
                                console.error('CloudConvert Process failed: ' + err);
                            } else {
                                console.log('Done: ' + conversionProcess.data.message);

                                // download it
                                conversionProcess.download(fs.createWriteStream("out.jpg"), null, function (err, conversionProcess) {
                                    if (err) {
                                        console.error('CloudConvert Process download failed: ' + err);
                                    } else {
                                        console.log('Downloaded to out.jpg');
                                    }
                                });
                            }

                        });
                    }
                });


            }
        });
    }

});

Download of multiple output files

In some cases it might be possible that there are multiple output files (e.g. converting a multi-page PDF to JPG). You can download them all to one directory using the downloadAll() method.

var fs = require('fs');
var cloudconvert = new (require('cloudconvert'))('your_api_key');

fs.createReadStream('tests/input.pdf').pipe(cloudconvert.convert({
    inputformat: 'pdf',
    outputformat: 'jpg',
    converteroptions: {
        page_range : '1-3',
    }
}).on('error', function(err) {
    console.error('Failed: ' + err);
}).on('finished', function(data) {
    console.log('Done: ' + data.message);
    this.downloadAll('tests/');
}).on('downloaded', function(destination) {
    console.log('Downloaded to: ' + destination.path);
}).on('downloadedAll', function(path) {
    console.log('Downloaded all to: ' + path);
}));

Events

The Processobject emits the following Events:

Event|Description ------|------------ error| The conversion failed. You should always listen for this event: If there is no listener, the error will be thrown and might crash your application. finished| The conversion is finished (but not yet downloaded). This event will only be emitted, if you do wait() for the process. (convert() does this automatically for you). progress|Emitted every second with the current progress of the conversion. This event will only be emitted, if you do wait() for the process. uploaded|The input file was uploaded. started|The process was started. downloaded|The output file was downloaded. downloadedAll|Emitted after completed downloadAll(). Every single file will emit a seperate downloaded event.

Error handling

The following example shows how to catch the different error types which can occur at conversions:

var fs = require('fs');
var cloudconvert = new (require('cloudconvert'))('your_api_key');

fs.createReadStream('tests/input.pdf').pipe(cloudconvert.convert({
    inputformat: 'pdf',
    outputformat: 'jpg',
}).on('error', function(err) {
    switch (err.code) {
        case 400:
            console.error('Something with your request is wrong: ' + err);
            break;
        case 422:
            console.error('Conversion failed, maybe because of a broken input file: ' + err);
            break;
        case 503:
            console.error('API temporary unavailable: ' + err);
            console.error('We should retry the conversion in ' + err.retryAfter + ' seconds');
            break;
        default:
            // network problems, etc..
            console.error('Something else went wrong: ' + err);
            break;
    }
}).on('finished', function(data) {
    console.log('Done: ' + data.message);
}));

How to run tests?

Tests are based on mocha:

git https://github.com/cloudconvert/cloudconvert-node.git
cd cloudconvert-node
npm install -d
npm test

How to run integration tests?

By default, mocha does not run integration tests against the real CloudConvert API. To run integration tests, use the API_KEY enviroment variable and run the integration tests:

git https://github.com/cloudconvert/cloudconvert-node.git
cd cloudconvert-node
npm install -d
export API_KEY="your_api_key"
npm run integration

Resources

• API Documentation
• Conversion Types
• CloudConvert Blog