SDK, CLI & Embed

Three official packages on npm. All of them call the same REST API with the same API keys.

Overview

SDK
@shablonix/sdk
TypeScript client for PDF generation, batches, email compile, embed sessions, and webhook verification.

Server · Node 18+, Deno, Bun, edge workers
View on npm
Embedded editor
@shablonix/embed
Mount the email, PDF, or website editor in your own app as an iframe with a typed postMessage API.

Browser · any framework, no dependencies
View on npm
CLI
@shablonix/cli
Generate documents, submit CSV/JSON batches, poll jobs, and download files from a terminal, CI job, or agent.

Terminal · Node 20.12+
View on npm

SDK

@shablonix/sdk ships ESM and CommonJS builds with TypeScript types. Keep the API key on your server.

npm install @shablonix/sdk

import { Shablonix } from '@shablonix/sdk';

const client = new Shablonix(process.env.SHABLONIX_API_KEY!);

const pdf = await client.generatePdf({
  templateId: 'meridian-invoice',
  data: { invoice: { number: 'INV-2026-001' } },
});
const bytes = await client.downloadGenerationBytes(pdf);

const letter = await client.compileEmail({
  templateId: 'cmEmailTemplateId',
  data: { customer: { name: 'Ada Lovelace' } },
});

Also covers batches, embed sessions, and constructWebhookEvent for verifying webhooks.

Sync, async, or stream

Method	Returns	Use when
generatePdf()	Completed metadata with `fileUrl`; file kept 72 h	You want a download link or to fetch the file later
generatePdf({ async: true }) generatePdfAndWait()	A pending job; poll with `waitForGeneration()` or receive a webhook	Large documents, queues, or requests you must not hold open
generatePdfStream() generatePdfBytes()	The file itself, as a `ReadableStream` or bytes; without an idempotency key no file is kept after it is sent	Piping a PDF straight to your user, S3, or disk in one request

Stream a PDF to your own HTTP response typescript

import { Readable } from 'node:stream';

app.get('/invoices/:id.pdf', async (req, res) => {
  const pdf = await client.generatePdfStream(
    { templateId: 'meridian-invoice', data: await loadInvoice(req.params.id) },
    { idempotencyKey: `invoice-${req.params.id}` }, // optional: safe retries
  );

  res.setHeader('Content-Type', pdf.contentType);
  if (pdf.contentLength) res.setHeader('Content-Length', pdf.contentLength);
  Readable.fromWeb(pdf.body).pipe(res);
});

generateStream() and generateBytes() do the same for HTML and DOCX. Every generate method accepts idempotencyKey. See Direct file response and Idempotency for the API contract.

Embedded editor

@shablonix/embed puts the Shablonix email, PDF, or website editor inside your product. Your backend mints a one-time session with the SDK; the browser only receives the session URL.

npm install @shablonix/embed

server typescript

const session = await shablonix.createEmbedSession({
  origin: 'https://your-app.example',
  starter: 'lookbook',
  userId: accountId,
});
// send session.url to the browser

browser typescript

import { mountEmailEditor } from '@shablonix/embed';

const editor = mountEmailEditor('#email-editor', {
  src: session.url,
  theme: 'light',
  onReady() { editor.load({ sampleData: currentRecord }); },
  onSave({ templateId, html, json }) { /* persist on your server */ },
});

mountPdfEditor and mountWebsiteEditor take the same options. Messages are only accepted from the session origin. See the embedded editor overview.

CLI

@shablonix/cli generates documents and batches without writing code. It suits one-off runs, CI jobs, and AI agents.

npm install -g @shablonix/cli
shablonix auth login --key-stdin < ./shablonix-api-key
shablonix generate --template cm123 --data-file invoice.json --output invoice.pdf
shablonix generate --template cm123 --data-file invoice.json --stream --output invoice.pdf

Full command reference: CLI guide.

Which one to use

You want to…	Use
Generate PDFs or compile email from your backend	@shablonix/sdk
Let your users design templates inside your app	@shablonix/embed + @shablonix/sdk
Run a batch from a CSV, script a CI step, or give an agent a tool	@shablonix/cli
Call from another language	REST API

Same keys everywhere

Create API keys under Dashboard → API Keys. The SDK and CLI use them directly; the embedded editor uses them only on your server to mint sessions.