@doclinth/sdk

Official Node/TypeScript SDK for the Doclinth PDF generation API. Zero dependencies, fully typed, with automatic retries.

Install

npm install @doclinth/sdk

Requires Node 18+ (uses the global fetch). On older runtimes pass your own fetch via options.fetch.

Usage

import { Doclinth } from "@doclinth/sdk";

const doclinth = new Doclinth({
  apiKey: process.env.DOCLINTH_API_KEY!,
  baseUrl: "https://doclinth.com", // or set DOCLINTH_BASE_URL
});

// Binary (default) — returns the PDF bytes.
const pdf = await doclinth.generate({
  templateId: "b1c2d3e4-…",
  data: { invoice_number: "INV-1042", total: 2592 },
});
await fs.writeFile("invoice.pdf", pdf);

// Signed URL — returns { url, expiresAt }.
const { url, expiresAt } = await doclinth.generate({
  templateId: "b1c2d3e4-…",
  data: { total: 2592 },
  output: "url",
});

// Per-request render options (format, landscape, margins, metadata, filename).
// watermark is paid plans only.
const labeled = await doclinth.generate({
  templateId: "b1c2d3e4-…",
  data: { total: 2592 },
  format: "Letter",
  landscape: false,
  margins: { top: "20mm", right: "16mm", bottom: "20mm", left: "16mm" },
  metadata: { title: "Invoice 1042", author: "Acme Billing" },
  filename: "invoice-1042.pdf",
  strict: true,
});

Templates

Discover template ids, learn a template's data contract, and author new templates from a prompt — the same surface an agent uses over MCP.

// List your templates.
const templates = await doclinth.listTemplates();

// Learn exactly what `data` a template expects before you render it.
const detail = await doclinth.getTemplate(templates[0].id);
detail.variables; // ["customer.name", "items", "total", …]
detail.sampleData; // a realistic example payload

// AI-author a new template from a description. It is saved as a DRAFT —
// generate keeps rendering the last published version until you publish it in
// the dashboard. Consumes your monthly AI-authoring allowance.
const created = await doclinth.createTemplate({
  prompt: "A packing slip with an order number, ship-to address, and a line-item table",
});
created.id; // pass this to getTemplate / generate once published

// Check the status of a past generation (by its X-Request-Id).
const status = await doclinth.getGeneration("req_…");
status.status; // "success" | "error"

Retries & idempotency

By default the client retries 429 and 5xx responses (and network errors) up to twice with exponential backoff, honoring Retry-After. To make those retries safe, generate attaches an Idempotency-Key automatically — so a retried request can never generate (or bill) a second PDF. Provide your own key to dedupe across process restarts:

await doclinth.generate({ templateId: "b1c2d3e4-…", data, idempotencyKey: orderId });

Set maxRetries: 0 to disable retries (and the automatic key). createTemplate is non-idempotent and AI-metered, so it only retries a pre-work 429, never a 5xx — a dropped response never risks a duplicate (billed) template.

Errors

Non-2xx responses throw a DoclinthError with a stable code and status:

import { Doclinth, DoclinthError } from "@doclinth/sdk";

try {
  await doclinth.generate({ templateId, data });
} catch (e) {
  if (e instanceof DoclinthError && e.code === "quota_exceeded") {
    // prompt an upgrade
  }
}

See the error reference for all codes.