@cloudraker/carbone-sdk

TypeScript SDK for the Carbone API — generate PDF, DOCX, XLSX, PPTX, and more from templates.

Fork Notice

This package is based on the official Carbone SDK for JavaScript. It has been:

• Rewritten in TypeScript with full type definitions
• Rebuilt for Cloudflare Workers and edge runtimes (Deno, Bun, Node 18+)

Key Changes from Original SDK

| Original (Node.js) | This Package (Edge) | |-------------------|---------------------| | Buffer | ArrayBuffer | | fs.readFileSync() / file paths | ArrayBuffer or template ID only | | Node.js stream | Promises with fetch() | | crypto.createHash() | crypto.subtle (Web Crypto) | | simple-get / http module | Native fetch() API | | Callbacks + Promises + Streams | Promises only (async/await) | | form-data package | Web FormData API |

Zero runtime dependencies — uses only Web Standard APIs.

Installation

npm install @cloudraker/carbone-sdk

Quick Start

import createCarboneSDK from '@cloudraker/carbone-sdk';

const carbone = createCarboneSDK('YOUR_API_KEY');

// Render a document
const { content, filename } = await carbone.render(
  templateArrayBuffer,
  { data: { name: 'John Doe', company: 'Acme Inc.' } }
);

Cloudflare Workers Example

import createCarboneSDK from '@cloudraker/carbone-sdk';

interface Env {
  CARBONE_API_KEY: string;
  TEMPLATES: R2Bucket;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const carbone = createCarboneSDK(env.CARBONE_API_KEY);

    // Get template from R2
    const templateObj = await env.TEMPLATES.get('invoice.docx');
    if (!templateObj) {
      return new Response('Template not found', { status: 404 });
    }

    const templateBuffer = await templateObj.arrayBuffer();

    // Render the document
    const { content, filename } = await carbone.render(templateBuffer, {
      data: {
        invoice_number: 'INV-2024-001',
        customer: 'Acme Corporation',
        total: 549.85
      },
      convertTo: 'pdf'
    });

    return new Response(content, {
      headers: {
        'Content-Type': 'application/pdf',
        'Content-Disposition': `attachment; filename="${filename}"`
      }
    });
  }
};

API

createCarboneSDK(apiKey: string)

Creates a new SDK instance.

const carbone = createCarboneSDK('YOUR_API_KEY');

render(template, data, options?)

Renders a template with the provided data.

Parameters:

• template — Template ID (64-char hash) or ArrayBuffer
• data — Object containing data and optional convertTo, payload
• options — Optional headers (e.g., webhook URL)

Returns: Promise<{ content: ArrayBuffer, filename: string }>

// With template ID
const result = await carbone.render(
  'b94b02964087ade5026ac4607be30493983345e5fa22ddea3229fc650210436c',
  { data: { name: 'John' } }
);

// With ArrayBuffer
const result = await carbone.render(
  templateArrayBuffer,
  { data: { name: 'John' }, convertTo: 'pdf' }
);

// Ephemeral template (not stored on Carbone servers)
const result = await carbone.render(
  templateArrayBuffer,
  { data: { name: 'John' } },
  { headers: { 'carbone-template-delete-after': '0' } }
);

addTemplate(template, payload?)

Uploads a template to Carbone.

Parameters:

• template — ArrayBuffer of the template file
• payload — Optional payload string for template hashing

Returns: Promise<string> — Template ID

const templateId = await carbone.addTemplate(templateArrayBuffer);

getTemplate(templateId)

Downloads a template from Carbone.

Returns: Promise<ArrayBuffer>

const templateBuffer = await carbone.getTemplate(templateId);

delTemplate(templateId)

Deletes a template from Carbone.

Returns: Promise<void>

await carbone.delTemplate(templateId);

setOptions(config)

Updates SDK configuration.

carbone.setOptions({
  carboneUrl: 'https://api.carbone.io/',  // API endpoint
  isReturningBuffer: true,                 // Return ArrayBuffer (true) or URL (false)
  retriesOnError: 3,                       // Retry count on network errors
  retriesIntervalOnError: 1000,            // Delay between retries (ms)
  headers: {
    'carbone-template-delete-after': 86400 // Auto-delete after 24h
  }
});

setApiVersion(version)

Sets the Carbone API version.

carbone.setApiVersion('4');

getFilename(headers)

Extracts filename from response headers.

const filename = carbone.getFilename(response.headers);

Template Sources

Templates can be provided as:

| Source | Example | |--------|---------| | ArrayBuffer | From R2, KV, fetch, or any binary source | | Template ID | 64-character hash from addTemplate() |

Note: File paths are not supported. Load files into an ArrayBuffer first.

Webhook Support

For async rendering with webhooks:

const result = await carbone.render(
  templateId,
  { data: { name: 'John' } },
  { headers: { 'carbone-webhook-url': 'https://your-app.com/webhook' } }
);
// Carbone will POST the rendered document to your webhook

License

Apache-2.0

Credits

Based on the official Carbone SDK by Carbone.io.