TypeScript SDK

Run prompts and workflows, manage knowledge bases, and verify webhooks from TypeScript.

The PromptJuggler TypeScript SDK is a thin, typed wrapper over the public REST API. You call flat, async methods and get back typed objects — authentication, request building, and JSON (de)serialization are handled for you. It runs in Node.js and any runtime with a global fetch.

Requirements

• Node.js 22 or newer

Installation

npm install @promptjuggler/sdk

Set up the client

Create an API key in Settings, then construct the client once and reuse it:

import { PromptJuggler } from '@promptjuggler/sdk';

const pj = new PromptJuggler('your-api-key');

The key is sent as a Bearer token to https://promptjuggler.com. Point the SDK at another host (e.g. for testing) with the baseUrl option, or inject a custom fetch.

Per-endpoint usage

Every endpoint in the API reference includes a TypeScript SDK code sample showing the exact call — that’s the place to look for how to invoke each operation and what it returns. A typical flow:

import { RunStatus } from '@promptjuggler/sdk';

// Trigger a run (async — returns immediately with the run ID)
const created = await pj.runPrompt('greeting', 'production', { name: 'Ada' });

// Poll for the result
const run = await pj.getPromptRun(created.id);
if (run.status === RunStatus.Completed) {
  console.log(run.output);
}

Methods return generated model objects with typed fields. They are plain, read-only data — read the fields, don’t write them back. An enum field can hold a value added to the API after your SDK version, outside its declared union.

Error handling

When the API responds with an error status, the SDK throws an ApiError carrying the HTTP status code and the server’s message. When the request never reaches the API (DNS failure, timeout, offline), it throws a ConnectionError. When the API replies with a success status but the SDK can’t decode the body, it throws a DecodeError: the request succeeded, so retrying a run starts a second one. All three extend the PromptJugglerError base class, so you can catch the whole surface at once.

import { ApiError } from '@promptjuggler/sdk';

try {
  const run = await pj.getPromptRun('does-not-exist');
} catch (error) {
  if (error instanceof ApiError) {
    error.statusCode; // e.g. 404
    error.message; // the server's error message
  }
}

You never catch a generated-client error — the SDK translates the underlying client’s errors into its own.

Webhooks

PromptJuggler signs every webhook with the PromptJuggler-Signature header. Verify it against the raw request body, before any JSON parsing:

import { verifyWebhookSignature } from '@promptjuggler/sdk';

const payload = await request.text(); // the raw body
const signature = request.headers.get('PromptJuggler-Signature') ?? '';

if (!(await verifyWebhookSignature(payload, signature, 'your-webhook-secret'))) {
  // reject the delivery (e.g. respond 403)
}

const event = JSON.parse(payload);

verifyWebhookSignature recomputes the HMAC-SHA256 of {timestamp}.{raw_body}, compares it in constant time, and rejects deliveries whose timestamp falls outside a tolerance window (default 300s) to prevent replay. Widen or narrow it with the tolerance argument. It uses the Web Crypto API, so it runs in Node, edge runtimes, and browsers alike.