@pulp-engine/sdk — TypeScript client for the Pulp Engine API

Typed TypeScript/JavaScript client for the PulpEngine document generation API. Companion to the Python SDK (pulp-engine, in-repo at packages/sdk-python/; PyPI publish pending).

Install

Not yet published to npm. This SDK currently ships in-repo only; registry publication is pending trusted-publisher setup. Until then, consume it from the workspace (packages/sdk-typescript/) or vendor the built output. The commands below will work once the package is live on npm.

npm install @pulp-engine/sdk
# or
pnpm add @pulp-engine/sdk
# or
yarn add @pulp-engine/sdk

Requires Node.js 18 or later. The companion @pulp-engine/template-model package (containing typed shapes for Pulp Engine template definitions) is installed automatically as a transitive dependency.

Quick start

import { PulpEngineClient } from '@pulp-engine/sdk'

const client = new PulpEngineClient({
  baseUrl: 'https://your-pulp-engine.example.com',
  apiKey: 'dk_admin_...', // X-Api-Key auth
})

// Render a template to PDF
const pdfBytes = await client.render.pdf({
  template: 'invoice',
  data: { customerName: 'Acme Corp', amount: 12_345 },
})

// Dry-run (validate + exercise expressions without producing output, ~80× faster)
const result = await client.render.dryRun({
  template: 'invoice',
  data: { customerName: 'Acme Corp', amount: 12_345 },
})
if (!result.valid) {
  for (const err of result.expressions.errors) {
    console.error(`${err.location?.nodePath}: ${err.message}`)
  }
}

See the full API guide for every available operation.

Preview routes in production

The Pulp Engine OpenAPI spec this SDK is generated from includes /render/preview/html and /render/preview/pdf routes. In production (NODE_ENV=production), those routes return 404 unless the API operator has explicitly enabled them with PREVIEW_ROUTES_ENABLED=true. They are intended for the live editor, not for production rendering pipelines.

Before calling a preview method against an unknown deployment, query GET /capabilities at runtime and check the advertised preview capability. Use the production render endpoints (POST /render/pdf — POST /render is a deprecated alias — and the per-format routes POST /render/html|csv|xlsx|docx|pptx, plus POST /render/batch for bulk jobs) for all production document generation — they are always registered and are not affected by this flag.

Authentication

Pulp Engine supports two auth schemes:

| Scheme | Header | When to use | |---|---|---| | ApiKeyAuth | X-Api-Key: dk_admin_... | Server-to-server integrations | | EditorTokenAuth | X-Editor-Token: ... | Short-lived editor session tokens (8h TTL) |

Pass apiKey or editorToken to the PulpEngineClient constructor — the client attaches the correct header on every request.

Versioning

This SDK is version-locked with the Pulp Engine server release cadence. Every server release ships a matching SDK release with the same vX.Y.Z tag across TypeScript and Python. Installing @pulp-engine/[email protected] guarantees compatibility with Pulp Engine server 0.64.0.

Errors

All SDK errors surface as PulpEngineError instances:

import { PulpEngineError } from '@pulp-engine/sdk'

try {
  await client.render.pdf({ template: 'invoice', data })
} catch (err) {
  if (err instanceof PulpEngineError) {
    console.error(`${err.status}: ${err.message}`)
    if (err.location) {
      console.error(`  at ${err.location.nodePath}:${err.location.line}:${err.location.column}`)
    }
    if (err.suggestion) {
      console.error(`  did you mean: ${err.suggestion.suggestions.join(', ')}?`)
    }
  }
}

TypeScript types

The SDK ships complete type definitions for every request and response. Template types come from @pulp-engine/template-model:

import type { TemplateDefinition } from '@pulp-engine/template-model'

const myTemplate: TemplateDefinition = {
  root: { type: 'document', children: [/* ... */] },
  // ... fully typed against the Pulp Engine template schema
}

License

MIT