carbone-sdk - npm Package Compare versions

Comparing version 1.1.1 to 1.2.0

config.js

@@ -8,3 +8,3 @@ let _config = {
 
-let _version = '3';
+let _version = '4';
 
@@ -11,0 +11,0 @@ module.exports = {

package.json

 {
   "name": "carbone-sdk",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Carbone Render NodeJS SDK to generate reports easily (PDF, docx, xlsx, ods, odt, ...)",
@@ -29,4 +29,7 @@ "main": "index.js",
   },
+  "engines": {
+    "node": ">=14.0.0"
+  },
   "author": "",
   "license": "Apache-2.0"
 }

README.md

@@ -1,7 +0,7 @@
-# Carbone Render Node SDK
-[![GitHub release (latest by date)](https://img.shields.io/github/v/release/carboneio/carbone-sdk-node?style=for-the-badge&logo=python)](https://pypi.org/project/carbone-sdk)
+# Carbone Cloud API Node SDK
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/carboneio/carbone-sdk-node?style=for-the-badge)
 [![Documentation](https://img.shields.io/badge/documentation-yes-brightgreen.svg?style=for-the-badge)](./API-REFERENCE.md)
 
 
-The SDK to use [Carbone render](https://carbone.io) API easily.
+The SDK to use [Carbone Cloud API](https://carbone.io) easily.
 
@@ -19,61 +19,54 @@ > Carbone is a report generator (PDF, DOCX, XLSX, ODT, PPTX, ODS, XML, CSV...) using templates and JSON data.
 
-To use it, you will need your API key you can find on `Carbone Account` in the [API access](https://account.carbone.io/#/account/api) menu.
+## Getting started
 
-Once you have your API key, you can require the module.
+Try the following code to generate a report in 10 seconds. Insert:
+* Your API key ([available on Carbone account](https://account.carbone.io/))
+* The absolute path to your template (created from your text editor)
+* The JSON data-set you want to inject inside the document
 
 ```js
 const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')
-```
+const path       = require('path');
 
-*INFO: Each request executed in the SDK is retry once if the first reponse request is a `ECONNRESET` error*
-
-## Getting started
-
-Try the following code to render a report in 10 seconds. Just replace your API key, the template you want to render, add data.
-
-```js
-const carboneSDK = require('carbone-sdk')('YOUR-API-KEY');
-
-const data = {
+const options = {
   data: {
-    // Add your data here
+    /** YOUR DATA HERE **/
+    firstname: "John",
+    lastname:  "Wick"
   },
-  convertTo: 'pdf'
+  convertTo: "pdf"
+  /** List of other options: https://carbone.io/api-reference.html#render-reports **/
 }
 
-// Create a write stream with the report name as parameter.
-const writeStream = fs.createWriteStream(path.join(__dirname, 'report.odt'))
-// Pass the template path as first parameter, in this example 'test.odt' is the template.
-// Pass the data object as second parameter.
-const carboneStream = carboneSDK.render(path.join(__dirname, 'test', 'datasets', 'test.odt'), data)
+/** 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, options, (err, buffer, filename) => {
 
-carboneStream.on('error', (err) => {
-  console.error(err)
 })
-
-writeStream.on('close', () => {
-  console.log('File rendered')
-})
-
-carboneStream.pipe(writeStream)
 ```
+Note: Each request executed in the SDK is retry once if the first reponse request is a `ECONNRESET` errors
 
-## Carbone version
+## API
 
-You can set the version of Carbone you want to use. With this, you can upgrade your carbone version when you are ready.
+### Change Carbone version
 
-To set the version, call this function:
-
+To choose a specific version of Carbone Render API, use the following function.
+It is only possible to set a major version of Carbone.
 ```js
-carbone.setApiVersion(2) // Set the version of carbone to 2
+// Set the version of carbone to 4
+carboneSDK.setApiVersion(4)
 ```
 
-*Note:* You can only set the major version of carbone.
+### Pass headers
 
-## API
+Initialise a global header that will be set for each API request.
 
-All path you can give to carbone must be absolute path. Use the `path` module to get it.
-
 ```js
-const absolutePath = path.join(__dirname, 'path', 'to', 'file.odt')
+sdk.setOptions({
+  headers: {
+    'carbone-template-delete-after': 86400
+    'carbone-webhook-url': 'https://...'
+  }
+})
 ```
@@ -83,15 +76,16 @@
 
+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
+
 ```js
-carbone.addTemplate('/absolute/path/to/your/file', (err, templateId) => {
+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) => {
 
-**WARNING:** The file path must be absolute.
-
-You can add multiple times the same template and get different `templateId` thanks to the payload.
-
-```js
-carbone.addTemplate('/absolute/path/to/your/file', 'YOUR-PAYLOAD', (err, templateId) => {
-
 })
@@ -103,9 +97,9 @@ ```
 ```js
-carbone.getTemplate('templateId', (err, content) => {
+const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')
 
+carboneSDK.getTemplate('templateId', (err, fileContentAsBuffer) => {
+  /** Note: The content returned is a buffer and not a string **/
 })
 ```
 
-**WARNING:** The content returned is a buffer and not a string
-
 You can also get a template with stream.
@@ -115,3 +109,3 @@
 const writeStream = fs.createWriteStream('tmp.odt')
-const carboneStream = carbone.getTemplate('templateId')
+const carboneStream = carboneSDK.getTemplate('templateId')
 
@@ -124,3 +118,3 @@ carboneStream.on('error', (err) => {
   // Get the real filename here
-  let filename = carbone.getFilename(carboneStream)
+  let filename = carboneSDK.getFilename(carboneStream)
 })
@@ -136,4 +130,6 @@
 ```js
-carbone.delTemplate('templateId', (err) => {
+const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')
 
+carboneSDK.delTemplate('templateId', (err) => {
+
 })
@@ -146,20 +142,34 @@ ```
 
-The first way is to use the `templateId`.
+The first solution is to use a `templateId` (previously created from the method "addTemplate").
 
 ```js
-const dataToRender = {}
+const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')
 
-carbone.render('templateId', dataToRender, (err, buffer, filename) => {
+const options = {
+  data: { /** YOUR DATA HERE **/ },
+  convertTo: "pdf"
+  /** List of other options: https://carbone.io/api-reference.html#render-reports **/
+}
 
+carboneSDK.render('templateId', options, (err, buffer, filename) => {
+
 })
 ```
 
-Or if you don't want the buffer but juste the link to download it later, you can set the conf like this.
+Or if you don't want the buffer but juste the link to download it later, you can set the options `isReturningBuffer: false` to the SDK.
 
 ```js
-carbone.setOptions({
+const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')
+
+const options = {
+  data: { /** YOUR DATA HERE **/ },
+  convertTo: "pdf"
+  /** List of other options: https://carbone.io/api-reference.html#render-reports **/
+}
+
+carboneSDK.setOptions({
   isReturningBuffer: false
 })
 
-carbone.render('templateId', dataToRender, (err, downloadLink, filename) => {
+carboneSDK.render('templateId', options, (err, downloadLink, filename) => {
 
@@ -169,31 +179,37 @@ })
 
-The second way is to use the path of your local file. Using this method is the most safety way to avoid errors. Carbone engine deleted files which has not been used since a while. By using this method, if your file has been deleted, the SDK will automatically upload it again and return you the result.
+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
 
 ```js
-const dataToRender = {}
+const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')
 
-carbone.render('/absolute/path/to/your/file', dataToRender, (err, buffer, filename) => {
-
-})
-```
-
-**WARNING:** If you want to set a payload, it must be located in the data object
-
-```js
-const dataToRender = {
-  payload: 'MY-PAYLOAD'
+const options = {
+  data: {
+    /** YOUR DATA HERE **/
+    firstname: "John",
+    lastname:  "Wick"
+  },
+  convertTo: "pdf"
+  /** List of other options: https://carbone.io/api-reference.html#render-reports **/
 }
 
-carbone.render('/absolute/path/to/your/file', dataToRender, (err, buffer, filename) => {
+carboneSDK.render('/absolute/path/to/your/template', options, (err, buffer, filename) => {
 
 })
 ```
-
 You can also render you template and get result with a stream.
 
 ```js
-const dataToRender = {}
+const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')
 
+const options = {
+  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 = carbone.render('/absolute/path/to/your/file', dataToRender)
+const sdkStream = carboneSDK.render('/absolute/path/to/your/template', options)
 
@@ -206,3 +222,3 @@ sdkStream.on('error', (err) => {
   // Here you can get the real filename
-  let filename = carbone.getFilename(sdkStream)
+  let filename = carboneSDK.getFilename(sdkStream)
 })
@@ -220,3 +236,5 @@
 ```js
-carbone.addTemplatePromise('/absolute/path/to/your/file', 'OPTIONAL-PAYLOAD')
+const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')
+
+carboneSDK.addTemplatePromise('/absolute/path/to/your/template', 'OPTIONAL-PAYLOAD')
 .then(templateId => {
@@ -233,3 +251,5 @@
 ```js
-carbone.getTemplatePromise('templateId')
+const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')
+
+carboneSDK.getTemplatePromise('templateId')
 .then(content => {
@@ -246,3 +266,5 @@
 ```js
-carbone.delTemplatePromise('templateId', 'OPTIONAL-PAYLOAD')
+const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')
+
+carboneSDK.delTemplatePromise('templateId', 'OPTIONAL-PAYLOAD')
 .then(templateId => {
@@ -259,5 +281,11 @@
 ```js
-const dataToRender = {}
+const carboneSDK = require('carbone-sdk')('YOUR-API-KEY')
 
-carbone.renderPromise('/absolute/path/to/your/file', dataToRender)
+const options = {
+  data: { /** YOUR DATA HERE **/ },
+  convertTo: "pdf"
+  /** List of other options: https://carbone.io/api-reference.html#render-reports **/
+}
+
+carboneSDK.renderPromise('/absolute/path/to/your/template', options)
 .then(result => {
@@ -264,0 +292,0 @@ // result.content contains the rendered file

render.js

@@ -80,3 +80,4 @@ const get               = require('simple-get');
         'carbone-version': sdkConfig.getVersion(),
-        'content-type': 'application/json'
+        'content-type': 'application/json',
+        ...config.headers
       },
@@ -83,0 +84,0 @@ json: false, // if true, simple-get tries to Parse the response

templates.js

@@ -44,3 +44,4 @@ const get               = require('simple-get');
         "content-type": form.getHeaders()['content-type'],
-        'carbone-version': sdkConfig.getVersion()
+        'carbone-version': sdkConfig.getVersion(),
+        ...config.headers
       }
@@ -74,3 +75,4 @@ }, (err, response, body) => {
         authorization: `Bearer ${_apiKey}`,
-        'carbone-version': sdkConfig.getVersion()
+        'carbone-version': sdkConfig.getVersion(),
+        ...config.headers
       }
@@ -107,3 +109,4 @@ }, (err, response, body) => {
         authorization: `Bearer ${_apiKey}`,
-        'carbone-version': sdkConfig.getVersion()
+        'carbone-version': sdkConfig.getVersion(),
+        ...config.headers
       }
@@ -110,0 +113,0 @@ }, function(err, response) {

No alert changes

Improved metrics

Total package byte prevSize

37405

increased by3.73%

Lines of code

563

increased by0.72%

Number of lines in readme file

286

increased by10.85%

No dependency changes