{"id":39078919,"url":"https://github.com/carboneio/carbone-sdk-node","last_synced_at":"2026-01-17T18:28:46.512Z","repository":{"id":55995503,"uuid":"264983617","full_name":"carboneio/carbone-sdk-node","owner":"carboneio","description":"The node SDK to use Carbone render API easily.","archived":false,"fork":false,"pushed_at":"2024-05-06T16:54:20.000Z","size":113,"stargazers_count":5,"open_issues_count":7,"forks_count":1,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-05-06T18:11:17.293Z","etag":null,"topics":["document-conversion","libreoffice","microsoft-office","nodejs","pdf-generation","report-generator","template-engine"],"latest_commit_sha":null,"homepage":"https://carbone.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carboneio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-18T15:36:10.000Z","updated_at":"2024-05-06T16:52:55.000Z","dependencies_parsed_at":"2024-04-05T09:35:37.458Z","dependency_job_id":null,"html_url":"https://github.com/carboneio/carbone-sdk-node","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/carboneio/carbone-sdk-node","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carboneio%2Fcarbone-sdk-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carboneio%2Fcarbone-sdk-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carboneio%2Fcarbone-sdk-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carboneio%2Fcarbone-sdk-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carboneio","download_url":"https://codeload.github.com/carboneio/carbone-sdk-node/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carboneio%2Fcarbone-sdk-node/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28515587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T18:28:00.501Z","status":"ssl_error","status_checked_at":"2026-01-17T18:28:00.150Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["document-conversion","libreoffice","microsoft-office","nodejs","pdf-generation","report-generator","template-engine"],"created_at":"2026-01-17T18:28:46.382Z","updated_at":"2026-01-17T18:28:46.472Z","avatar_url":"https://github.com/carboneio.png","language":"JavaScript","readme":"# Carbone Cloud API Node SDK\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/carboneio/carbone-sdk-node?style=for-the-badge)\n[![Documentation](https://img.shields.io/badge/documentation-yes-brightgreen.svg?style=for-the-badge)](./API-REFERENCE.md)\n\n\nThe SDK to use [Carbone Cloud API](https://carbone.io) easily.\n\n\u003e Carbone is a report generator (PDF, DOCX, XLSX, ODT, PPTX, ODS, XML, CSV...) using templates and JSON data.\n[Learn more about the Carbone ecosystem](https://carbone.io/documentation.html).\n\n## Install\n\n```bash\n$ npm i --save carbone-sdk\n// OR\n$ yarn add carbone-sdk\n```\n\n## Getting started\n\nTry the following code to generate a report in 10 seconds. Insert:\n* Your API key ([available on Carbone account](https://account.carbone.io/))\n* The absolute path to your template (created from your text editor)\n* The JSON data-set you want to inject inside the document\n\n```js\nconst carboneSDK = require('carbone-sdk')('YOUR-API-KEY')\nconst path       = require('path');\n\nconst body = {\n  data: {\n    /** YOUR DATA HERE **/\n    firstname: \"John\",\n    lastname:  \"Wick\"\n  },\n  convertTo: \"pdf\"\n  /** List of other options: https://carbone.io/api-reference.html#render-reports **/\n}\n\n/** The template path must be absolute. Use the `path` module to get it. **/\nconst templateAbsolutePath = path.join(__dirname, 'path', 'to', 'template.odt')\n/** Generate the document **/\ncarboneSDK.render(templateAbsolutePath, body, (err, buffer, filename) =\u003e {\n/**\n * ✅ Document generated, returned values:\n * - \"buffer\": generated document as Buffer\n * - \"Filename\": document name as String\n * \n * Now you can save the file or Stream it!\n **/\n})\n```\nNote: Each request executed in the SDK is retry once if the first reponse request is a `ECONNRESET` errors\n\n## API\n\n### Change Carbone version\n\nTo choose a specific version of Carbone Render API, use the following function.\nIt is only possible to set a major version of Carbone.\n```js\n// Set the version of carbone to 4\ncarboneSDK.setApiVersion(4)\n```\n\n### Update default options / headers\n\n```js\ncarboneSDK.setOptions({\n  // Edit headers for all requests (default)\n  headers: {\n    'carbone-template-delete-after': 86400\n  },\n  // Edit the default Carbone URL (https://api.carbone.io/) for On-Premise\n  // WARNING: Add a trailing slash to the end of your URL\n  carboneUrl: 'https://your-on-premise-carbone-url:4000/'\n})\n```\n\n\n### Add a template\n\nWhen 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.\nFrom the template you can:\n* Generate a report\n* Delete a template\n* Download a template\n\n```js\nconst carboneSDK = require('carbone-sdk')('YOUR-API-KEY');\nconst path       = require('path');\n\n/** The template path must be absolute. Use the `path` module to get it. **/\nconst templateAbsolutePath = path.join(__dirname, 'path', 'to', 'template.odt')\ncarboneSDK.addTemplate(templateAbsolutePath, (err, templateId) =\u003e {\n\n})\n```\n\n### Get a template\n\n```js\nconst carboneSDK = require('carbone-sdk')('YOUR-API-KEY')\n\ncarboneSDK.getTemplate('templateId', (err, fileContentAsBuffer) =\u003e {\n  /** Note: The content returned is a buffer and not a string **/\n})\n```\n\nYou can also get a template with stream.\n\n```js\nconst writeStream = fs.createWriteStream('tmp.odt')\nconst carboneStream = carboneSDK.getTemplate('templateId')\n\ncarboneStream.on('error', (err) =\u003e {\n\n})\n\nwriteStream.on('close', () =\u003e {\n  // Get the real filename here\n  let filename = carboneSDK.getFilename(carboneStream)\n})\n\ncarboneStream.pipe(writeStream)\n```\n\n*The only way to get the filename when using stream is to wait the end of the request execution.*\n\n### Delete a template\n\n```js\nconst carboneSDK = require('carbone-sdk')('YOUR-API-KEY')\n\ncarboneSDK.delTemplate('templateId', (err) =\u003e {\n\n})\n```\n\n### Render a template\n\nThere are multiple ways to render a template.\n\nThe first solution is to use a `templateId` (previously created from the method \"addTemplate\").\n\n```js\nconst carboneSDK = require('carbone-sdk')('YOUR-API-KEY')\n\nconst body = {\n  data: { /** YOUR DATA HERE **/ },\n  convertTo: \"pdf\"\n  /** List of other options: https://carbone.io/api-reference.html#render-reports **/\n}\n\ncarboneSDK.render('templateId', body, (err, buffer, filename) =\u003e {\n\n})\n```\n\nOr 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.\n\n```js\nconst carboneSDK = require('carbone-sdk')('YOUR-API-KEY')\n\nconst body = {\n  data: { /** YOUR DATA HERE **/ },\n  convertTo: \"pdf\"\n  /** List of other options: https://carbone.io/api-reference.html#render-reports **/\n}\n\ncarboneSDK.setOptions({\n  isReturningBuffer: false\n})\n\ncarboneSDK.render('templateId', body, (err, downloadLink, filename) =\u003e {\n\n})\n```\n\nThe 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:\n* upload the template\n* generate the report\n* download the report as Buffer\n\n```js\nconst carboneSDK = require('carbone-sdk')('YOUR-API-KEY')\n\nconst body = {\n  data: {\n    /** YOUR DATA HERE **/\n    firstname: \"John\",\n    lastname:  \"Wick\"\n  },\n  convertTo: \"pdf\"\n  /** List of other options: https://carbone.io/api-reference.html#render-reports **/\n}\n\ncarboneSDK.render('/absolute/path/to/your/template', body, (err, buffer, filename) =\u003e {\n\n})\n```\nYou can also render you template and get result with a stream.\n\n```js\nconst carboneSDK = require('carbone-sdk')('YOUR-API-KEY')\n\nconst body = {\n  data: { /** YOUR DATA HERE **/ },\n  convertTo: \"pdf\"\n  /** List of other options: https://carbone.io/api-reference.html#render-reports **/\n}\n\nconst writeStream = fs.createWriteStream('result.pdf')\nconst sdkStream = carboneSDK.render('/absolute/path/to/your/template', body)\n\nsdkStream.on('error', (err) =\u003e {\n\n})\n\nwriteStream.on('close', () =\u003e {\n  // Here you can get the real filename\n  let filename = carboneSDK.getFilename(sdkStream)\n})\n\nsdkStream.pipe(writeStream)\n```\n\n\nYou can also overwrite headers with an optional object. Here is an example to use Carbone webhooks: \n\n```js\n\nconst options = {\n  headers = {\n    'carbone-webhook-url': 'https://...'\n  }\n}\n\ncarboneSDK.render('templateId', body, options, (err, buffer, filename) =\u003e {\n\n})\n```\n\n\n## API Promise\n\nAll function of the SDK are also available with promise.\n\n### Add a template\n\n```js\nconst carboneSDK = require('carbone-sdk')('YOUR-API-KEY')\n\ncarboneSDK.addTemplatePromise('/absolute/path/to/your/template', 'OPTIONAL-PAYLOAD')\n.then(templateId =\u003e {\n\n})\n.catch(err =\u003e {\n\n})\n```\n\n### Get a template\n\n```js\nconst carboneSDK = require('carbone-sdk')('YOUR-API-KEY')\n\ncarboneSDK.getTemplatePromise('templateId')\n.then(content =\u003e {\n\n})\n.catch(err =\u003e {\n\n})\n```\n\n### Delete a template\n\n```js\nconst carboneSDK = require('carbone-sdk')('YOUR-API-KEY')\n\ncarboneSDK.delTemplatePromise('templateId', 'OPTIONAL-PAYLOAD')\n.then(templateId =\u003e {\n\n})\n.catch(err =\u003e {\n\n})\n```\n\n### Render a template\n\n```js\nconst carboneSDK = require('carbone-sdk')('YOUR-API-KEY')\n\nconst body = {\n  data: { /** YOUR DATA HERE **/ },\n  convertTo: \"pdf\"\n  /** List of other options: https://carbone.io/api-reference.html#render-reports **/\n}\n\n// You can also overwrite headers with an optional object. Here is an example to use Carbone webhooks:\nconst options = {\n  headers : {\n    'carbone-webhook-url': 'https://...' // if you \n  }\n}\n\ncarboneSDK.renderPromise('/absolute/path/to/your/template', body [, options])\n.then(result =\u003e {\n  // result.content contains the rendered file\n  // result.filename containes the rendered filename\n})\n.catch(err =\u003e {\n\n})\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarboneio%2Fcarbone-sdk-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarboneio%2Fcarbone-sdk-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarboneio%2Fcarbone-sdk-node/lists"}