SDKs for Node.js and Python

import CastPDF from '@castpdf/sdk';

// reads CASTPDF_API_KEY, or pass { apiKey: 'cpdf_test_...' }
const castpdf = new CastPDF();

const me = await castpdf.me(); // the team, the plan and the key mode: a cheap connection test

from castpdf import CastPDF

client = CastPDF()  # reads CASTPDF_API_KEY, or CastPDF("cpdf_test_...")

me = client.me()  # the team, the plan and the key mode: a cheap connection test

import { writeFile } from 'node:fs/promises';

// a saved template filled with data, as a private download link
const pdf = await castpdf.pdfs.create({
  template_id: process.env.INVOICE_TEMPLATE_ID,
  data: { customer: { name: 'Ada Lovelace' }, items: [{ name: 'Consulting', qty: 2, price: 120 }] },
  test: true,
});
console.log(pdf.url, pdf.expires_at);

// raw HTML with Liquid, straight to a file
const file = await castpdf.pdfs.createFile({
  html: '<h1>Hello {{ name }}</h1>',
  data: { name: 'Ada' },
  format: 'A4',
  margins: '20mm',
  filename: 'hello.pdf',
});
await writeFile(file.filename ?? 'out.pdf', file.data);

import os
from pathlib import Path

# a saved template filled with data, as a private download link
pdf = client.pdfs.create(
    template_id=os.environ["INVOICE_TEMPLATE_ID"],
    data={"customer": {"name": "Ada Lovelace"}, "items": [{"name": "Consulting", "qty": 2, "price": 120}]},
    test=True,
)
print(pdf["url"], pdf["expires_at"])

# raw HTML with Liquid, straight to a file
f = client.pdfs.create_file(html="<h1>Hello {{ name }}</h1>", data={"name": "Ada"}, format="A4", margins="20mm")
Path(f.filename or "out.pdf").write_bytes(f.content)

const queued = await castpdf.pdfs.createAsync({ template_id, data, metadata: { order: '1042' } });

const doc = await castpdf.pdfs.waitFor(queued.id, { intervalMs: 2000, timeoutMs: 180_000 });
if (doc.status === 'succeeded') console.log(doc.url);
else console.log(doc.status, doc.error_code);

// later: the same document with a fresh signed url while it is stored
const again = await castpdf.pdfs.get(doc.id);

queued = client.pdfs.create_async(template_id=template_id, data=data, metadata={"order": "1042"})

doc = client.pdfs.wait_for(queued["id"], interval=2.0, timeout=180.0)
if doc["status"] == "succeeded":
    print(doc["url"])
else:
    print(doc["status"], doc.get("error_code"))

# later: the same document with a fresh signed url while it is stored
again = client.pdfs.get(doc["id"])

const { data: templates } = await castpdf.templates.list();
const fields = await castpdf.templates.fields(templates[0].id);
for (const f of fields.fields) console.log(f.key, f.type, f.sample);

const preview = await castpdf.templates.preview(templates[0].id, { data: { number: 'RE-1' } });

// live keys only: a new template, then a new version of it
const t = await castpdf.templates.create({ name: 'Invoice', html: '<h1>{{ number }}</h1>', sample_data: { number: 'RE-1' } });
await castpdf.templates.update(t.id, { html: '<h1>Invoice {{ number }}</h1>' });
await castpdf.templates.pin(t.id, 2); // renders use version 2; null unpins

templates = client.templates.list()["data"]
fields = client.templates.fields(templates[0]["id"])
for f in fields["fields"]:
    print(f["key"], f["type"], f["sample"])

preview = client.templates.preview(templates[0]["id"], data={"number": "RE-1"})

# live keys only: a new template, then a new version of it
t = client.templates.create(name="Invoice", html="<h1>{{ number }}</h1>", sample_data={"number": "RE-1"})
client.templates.update(t["id"], html="<h1>Invoice {{ number }}</h1>")
client.templates.pin(t["id"], 2)  # renders use version 2; None unpins

import express from 'express';
import { constructEvent, SignatureVerificationError } from '@castpdf/sdk';

const app = express();
app.post('/castpdf', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    const event = await constructEvent({
      payload: req.body, // a Buffer with the raw body
      header: req.get('castpdf-signature'),
      secret: process.env.CASTPDF_WEBHOOK_SECRET,
    });
    if (event.type === 'pdf.created') console.log('ready:', event.data.url);
    res.sendStatus(200);
  } catch (err) {
    if (err instanceof SignatureVerificationError) return res.sendStatus(400);
    throw err;
  }
});

import os
from flask import Flask, abort, request
from castpdf import SignatureVerificationError, construct_event

app = Flask(__name__)

@app.post("/castpdf")
def castpdf_webhook():
    try:
        event = construct_event(
            request.get_data(),  # the raw bytes
            request.headers.get("CastPDF-Signature"),
            os.environ["CASTPDF_WEBHOOK_SECRET"],
        )
    except SignatureVerificationError:
        abort(400)
    if event["type"] == "pdf.created":
        print("ready:", event["data"]["url"])
    return "", 200

const castpdf = new CastPDF({
  maxRetries: 3,
  timeoutMs: 60_000, // per attempt
  autoIdempotencyKeys: true, // a generated key on pdfs.create* and batches.create when you give none
});

await castpdf.pdfs.create({ template_id, data }, { idempotencyKey: `invoice-${order.id}`, timeoutMs: 30_000 });

client = CastPDF(
    max_retries=3,
    timeout=60.0,  # seconds per attempt
    auto_idempotency_keys=True,  # a generated key on pdfs.create* and batches.create when you give none
)

client.pdfs.create(template_id=template_id, data=data, idempotency_key=f"invoice-{order_id}")
client.me(request_options={"timeout": 10, "max_retries": 0})

import { NotFoundError, RateLimitError, BadRequestError } from '@castpdf/sdk';

try {
  await castpdf.pdfs.create({ template_id, data });
} catch (err) {
  if (err instanceof NotFoundError) console.log('No such template');
  else if (err instanceof RateLimitError) console.log(`Retry in ${err.retryAfter} s`);
  else if (err instanceof BadRequestError) console.log(err.code, err.details); // a Liquid error names its line
  else throw err;
}

from castpdf import BadRequestError, NotFoundError, RateLimitError

try:
    client.pdfs.create(template_id=template_id, data=data)
except NotFoundError:
    print("No such template")
except RateLimitError as err:
    print(f"Retry in {err.retry_after} s")
except BadRequestError as err:
    print(err.code, err.details)  # a Liquid error names its line