@promptwall/node

Official Node.js / TypeScript SDK for PromptWall — runtime governance for LLM applications. Detects prompt injection, verifies answer grounding, enforces policies, and ships a full audit trail.

• Zero runtime dependencies (uses native fetch on Node 18+)
• Full TypeScript types (ESM + CJS builds)
• Typed errors (AuthError, BlockedError, QuotaError, SubscriptionError, TimeoutError, APIError)
• Built-in retry with exponential backoff + Retry-After honoring on 429/5xx
• AbortSignal support for cancellation

Install

npm install @promptwall/node
# or
pnpm add @promptwall/node
# or
yarn add @promptwall/node

Requires Node.js 18+ (or any environment with global fetch).

Quickstart

import { PromptWall } from '@promptwall/node';

const pw = new PromptWall({ apiKey: process.env.PROMPTWALL_API_KEY });

const result = await pw.verify({
  prompt: 'What is the capital of France?',
  answer: 'Paris is the capital of France.',
  toolResult: 'Paris',
});

console.log(result.governance);          // 'allow' | 'rewrite' | 'block' | 'regenerate'
console.log(result.confidence);          // 'high' | 'medium' | 'low'
console.log(result.evidenceConsistent);  // true / false
console.log(result.requestId);           // for log correlation

PROMPTWALL_API_KEY is read from the environment automatically if you don't pass apiKey.

Modes

PromptWall supports three operational modes — all reachable from this SDK:

| Mode | Method | What it does | |---|---|---| | Verify | pw.verify(...) | Validate an answer you already have. Fastest, cheapest. | | Webhook (BYOK) | pw.chat(...) | Full pipeline; PromptWall calls your LLM key. | | Webhook (Managed) | pw.chat(...) | Full pipeline; PromptWall provides the LLM. |

Mode is determined by the API key you use. See the docs.

Verify mode

const r = await pw.verify({
  prompt: 'What was Q3 revenue?',
  answer: 'Q3 revenue was $12.4M.',
  toolResult: { quarter: 'Q3', revenue_usd: 12_400_000 },
  verifiedSourceUsed: true,
  groundingRequired: true,
});

if (r.governance === 'block') {
  // PromptWall blocked the answer (e.g. policy violation)
}
if (r.mismatchType === 'numeric') {
  // The answer's numbers don't match the source
}

Chat mode (full pipeline)

const r = await pw.chat({
  prompt: 'Summarize last week’s sales.',
  model: 'gpt-4o-mini',
  provider: 'openai',
  temperature: 0.2,
});

console.log(r.answer);
console.log(r.tokens);                   // { prompt, completion, total }
console.log(r.verifiedSourceUsed);       // true if a tool was used to ground the answer

Tool registry (webhooks)

Register webhook tools that PromptWall can call to ground answers. PromptWall returns a signingSecret you use to verify HMAC-SHA256 signatures on incoming calls.

const tool = await pw.tools.register({
  name: 'billing_api',
  webhookUrl: 'https://api.acme.com/v1/billing',
  authType: 'bearer',
  authToken: process.env.BILLING_API_TOKEN,
  category: 'metrics',
  groundingKeywords: ['revenue', 'mrr', 'billing'],
  trustTier: 'customer',
  timeoutMs: 5_000,
  rateLimitRpm: 60,
});

console.log('Save this:', tool.signingSecret);

// Probe connectivity
const health = await pw.tools.test(tool.id);
console.log(health.ok, health.statusCode, health.latencyMs);

// List all tools
const tools = await pw.tools.list();

Usage

const usage = await pw.usage.current();
//   { requestsUsed, requestsIncluded, tokensUsed, periodStart, periodEnd, overageUsd }

const series = await pw.usage.timeseries(14); // last 14 days

Error handling

Every error thrown by the SDK is an instance of PromptWallError. Use instanceof to handle them:

import {
  PromptWall,
  AuthError,
  BlockedError,
  QuotaError,
  SubscriptionError,
  TimeoutError,
  APIError,
} from '@promptwall/node';

try {
  await pw.verify({ prompt, answer });
} catch (err) {
  if (err instanceof BlockedError)        { /* policy blocked the request */ }
  else if (err instanceof QuotaError)     { /* err.retryAfterMs */ }
  else if (err instanceof SubscriptionError) { /* upgrade required */ }
  else if (err instanceof AuthError)      { /* bad API key */ }
  else if (err instanceof TimeoutError)   { /* request slow / network */ }
  else if (err instanceof APIError)       { /* 5xx, network error */ }
  else throw err;
}

Every error carries status, code, requestId, and raw (the original payload).

Cancellation

Pass an AbortSignal to cancel mid-flight:

const ctrl = new AbortController();
setTimeout(() => ctrl.abort(), 500);

await pw.verify({ prompt, answer }, { signal: ctrl.signal });

Configuration

const pw = new PromptWall({
  apiKey: 'pk_live_...',                   // or PROMPTWALL_API_KEY
  baseUrl: 'https://api.prompt-wall.com',  // override for self-hosted
  timeoutMs: 30_000,                       // per-request timeout
  maxRetries: 2,                           // 0 = disabled; retries 408/425/429/5xx
  defaultHeaders: { 'X-Tenant': 'acme' },  // merged into every request
  fetch: customFetch,                      // optional custom fetch impl
});

License

MIT © PromptWall