npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

carbone-sdk

v1.6.0

Published

Carbone API NodeJS SDK to generate documents: PDF, DOCX, XLSX, PPTX, ODT, ODP, ODS, CSV, JPG, PNG, invoices, reports, financial, contracts, financial statements and more.

Downloads

3,500

Readme

Carbone Cloud API Node SDK

GitHub release (latest by date) Documentation

The SDK to use Carbone Cloud API easily.

Carbone is a report generator (PDF, DOCX, XLSX, ODT, PPTX, ODS, XML, CSV...) using templates and JSON data. Learn more about the Carbone ecosystem.

Install

$ npm i --save carbone-sdk
// OR
$ yarn add carbone-sdk

Getting started

Try the following code to generate a report in 10 seconds. Insert:

  • Your API key (available on Carbone account)
  • The absolute path to your template (created from your text editor)
  • The JSON data-set you want to inject inside the document
const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')
const path       = require('path');

const body = {
  data: {
    /** YOUR DATA HERE **/
    firstname: "John",
    lastname:  "Wick"
  },
  convertTo: "pdf"
  /** List of other options: https://carbone.io/api-reference.html#render-reports **/
}

/** The template path must be absolute. Use the `path` module to get it. **/
const templateAbsolutePath = path.join(__dirname, 'path', 'to', 'template.odt')
/** Generate the document **/
carboneSDK.render(templateAbsolutePath, body, (err, buffer, filename) => {
/**
 * ✅ Document generated, returned values:
 * - "buffer": generated document as Buffer
 * - "Filename": document name as String
 * 
 * Now you can save the file or Stream it!
 **/
})

Note: Each request executed in the SDK is retry once if the first reponse request is a ECONNRESET errors

API

Change Carbone version

To choose a specific version of Carbone Render API, use the following function. It is only possible to set a major version of Carbone.

// Set the version of carbone to 4
carboneSDK.setApiVersion(4)

Update default options / headers

carboneSDK.setOptions({
  // Edit headers for all requests (default)
  headers: {
    'carbone-template-delete-after': 86400
  },
  // Edit the default Carbone URL (https://api.carbone.io/) for On-Premise
  // WARNING: Add a trailing slash to the end of your URL
  carboneUrl: 'https://your-on-premise-carbone-url:4000/'
})

Add a template

When a template is uploaded, a Template ID is created which is the unique identifier for the template. If you upload the same template twice, you will have the same Template ID. From the template you can:

  • Generate a report
  • Delete a template
  • Download a template
const carboneSDK = require('carbone-sdk')('YOUR-API-KEY');
const path       = require('path');

/** The template path must be absolute. Use the `path` module to get it. **/
const templateAbsolutePath = path.join(__dirname, 'path', 'to', 'template.odt')
carboneSDK.addTemplate(templateAbsolutePath, (err, templateId) => {

})

Get a template

const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')

carboneSDK.getTemplate('templateId', (err, fileContentAsBuffer) => {
  /** Note: The content returned is a buffer and not a string **/
})

You can also get a template with stream.

const writeStream = fs.createWriteStream('tmp.odt')
const carboneStream = carboneSDK.getTemplate('templateId')

carboneStream.on('error', (err) => {

})

writeStream.on('close', () => {
  // Get the real filename here
  let filename = carboneSDK.getFilename(carboneStream)
})

carboneStream.pipe(writeStream)

The only way to get the filename when using stream is to wait the end of the request execution.

Delete a template

const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')

carboneSDK.delTemplate('templateId', (err) => {

})

Render a template

There are multiple ways to render a template.

The first solution is to use a templateId (previously created from the method "addTemplate").

const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')

const body = {
  data: { /** YOUR DATA HERE **/ },
  convertTo: "pdf"
  /** List of other options: https://carbone.io/api-reference.html#render-reports **/
}

carboneSDK.render('templateId', body, (err, buffer, filename) => {

})

Or if you don't want the buffer but just the link to download it later, you can set the options isReturningBuffer: false to the SDK.

const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')

const body = {
  data: { /** YOUR DATA HERE **/ },
  convertTo: "pdf"
  /** List of other options: https://carbone.io/api-reference.html#render-reports **/
}

carboneSDK.setOptions({
  isReturningBuffer: false
})

carboneSDK.render('templateId', body, (err, downloadLink, filename) => {

})

The second solution (and easiest one) is to write the path of your local file, not the template ID. By using this method, if your template does not exist or has been deleted, the SDK will automatically:

  • upload the template
  • generate the report
  • download the report as Buffer
const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')

const body = {
  data: {
    /** YOUR DATA HERE **/
    firstname: "John",
    lastname:  "Wick"
  },
  convertTo: "pdf"
  /** List of other options: https://carbone.io/api-reference.html#render-reports **/
}

carboneSDK.render('/absolute/path/to/your/template', body, (err, buffer, filename) => {

})

You can also render you template and get result with a stream.

const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')

const body = {
  data: { /** YOUR DATA HERE **/ },
  convertTo: "pdf"
  /** List of other options: https://carbone.io/api-reference.html#render-reports **/
}

const writeStream = fs.createWriteStream('result.pdf')
const sdkStream = carboneSDK.render('/absolute/path/to/your/template', body)

sdkStream.on('error', (err) => {

})

writeStream.on('close', () => {
  // Here you can get the real filename
  let filename = carboneSDK.getFilename(sdkStream)
})

sdkStream.pipe(writeStream)

You can also overwrite headers with an optional object. Here is an example to use Carbone webhooks:


const options = {
  headers = {
    'carbone-webhook-url': 'https://...'
  }
}

carboneSDK.render('templateId', body, options, (err, buffer, filename) => {

})

API Promise

All function of the SDK are also available with promise.

Add a template

const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')

carboneSDK.addTemplatePromise('/absolute/path/to/your/template', 'OPTIONAL-PAYLOAD')
.then(templateId => {

})
.catch(err => {

})

Get a template

const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')

carboneSDK.getTemplatePromise('templateId')
.then(content => {

})
.catch(err => {

})

Delete a template

const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')

carboneSDK.delTemplatePromise('templateId', 'OPTIONAL-PAYLOAD')
.then(templateId => {

})
.catch(err => {

})

Render a template

const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')

const body = {
  data: { /** YOUR DATA HERE **/ },
  convertTo: "pdf"
  /** List of other options: https://carbone.io/api-reference.html#render-reports **/
}

// You can also overwrite headers with an optional object. Here is an example to use Carbone webhooks:
const options = {
  headers : {
    'carbone-webhook-url': 'https://...' // if you 
  }
}

carboneSDK.renderPromise('/absolute/path/to/your/template', body [, options])
.then(result => {
  // result.content contains the rendered file
  // result.filename containes the rendered filename
})
.catch(err => {

})