SDK quickstart

@promptv/sdk is the Node.js client for PromptVault. Fetch versioned prompts from your application code, optionally interpolate variables, and serve them ready-to-send to any LLM.

Install

npm install @promptv/sdk

Requires Node 18 or newer.

First call

import { promptvault } from "@promptv/sdk";

const pv = promptvault({ key: process.env.PROMPTV_KEY! });

const prompt = await pv.get("support-triage");

console.log(prompt.version);   // "v22"
console.log(prompt.messages);  // [{ role: "system", content }, { role: "user", content }]

// Send straight to any chat API:
await openai.chat.completions.create({
  model: prompt.model,
  messages: prompt.messages,
});

pv.get() returns a Prompt object (not a string) - the SDK's normalized return shape:

{
  slug: string;
  folder: string;
  model: string;
  temperature: number;
  version: string;       // version label served (e.g. "v22")
  source: string;        // system + user concatenated (interpolated or raw)
  systemSource: string;  // system role content
  userSource: string;    // user role content ("" if none)
  messages: Array<{ role: "system" | "user"; content: string }>; // empty roles omitted
  variables: string[];   // names of all tokens detected in the original source
}

Use prompt.messages for chat APIs; prompt.source is the legacy single-string form (system + user joined by a blank line). Legacy single-prompt entries with no user role come back as a one-element messages array with role: "system".

Live vs. test environment

The key prefix decides what each .get() returns:

Mint both flavours in the dashboard's Settings → API keys. Use pv_live_ in production and pv_test_ in CI / staging - same SDK code, different env var.

Interpolating variables

const prompt = await pv.get("onboarding-email", {
  variables: { recipient_name: "Maya" },
});

{{recipient_name}} and {recipient_name} are both replaced. Unknown tokens are left intact. Disable interpolation with interpolate: false to retrieve the raw source. See Variables.

Caching, by default

promptvault({ key }) returns a client whose cache is a downtime-only fallback - ttl: 0. Every read hits the live API, so a dashboard publish is picked up on the next read with no delay. The cache holds the last value each slug returned and serves it only when a live read fails (network error, timeout, or 5xx), as long as that slug was warmed at least once.

Opt into a freshness window, or replace the store:

promptvault({ key, cache: { ttl: 10_000 } });                            // 10 s freshness window
promptvault({ key, cache: { ttl: 30_000, staleWhileRevalidate: 60_000 } }); // + serve-stale + bg refresh
promptvault({ key, cache: { ttl: 0 } });                                 // downtime-only (the default)
promptvault({ key, cache: false });                                      // no caching, no fallback
promptvault({ key, cache: { store: redisStore } });                      // Redis or any custom store

There's also a per-request timeout (default 100 ms): a slow read is treated as a down read, aborted, and served from the fallback. See Caching and API reference for the precise rules.

Methods at a glance

Full reference in API reference.

Errors

Every SDK error is a PromptVaultError with a typed code:

See Errors.

Where to read next

• API reference - every method and option.
• Caching - fallback, TTL, stale-while-revalidate, custom stores.
• Variables - token syntax and validation.
• Errors - typed codes and recovery patterns.