API reference

Complete reference for @promptv/sdk. All exports come from the package root:

import {
  promptvault,
  PromptVaultClient,
  PromptVaultError,
  MemoryCacheStore,
  HttpTransport,
  DEFAULT_TIMEOUT_MS,
  pullSnapshot,
  SNAPSHOT_SCHEMA,
  type Prompt,
  type Message,
  type MessageRole,
  type PromptSummary,
  type Version,
  type GetOptions,
  type PromptVaultOptions,
  type CacheConfig,
  type CacheOptions,
  type CacheStore,
  type CacheEntry,
  type VariableValue,
  type PromptVaultErrorCode,
  type HttpTransportOptions,
  type Transport,
  type RawPromptRecord,
  type RawVersion,
  type PromptVaultSnapshot,
  type PullSnapshotOptions,
} from "@promptv/sdk";

`promptvault(options)`

Factory that constructs and returns a PromptVaultClient.

const pv = promptvault({
  key: process.env.PROMPTV_KEY!,
  // cache?: boolean | CacheOptions,
  // timeout?: number,
});

`PromptVaultOptions`

Field	Type	Default	Notes
`key`	`string`	-	Required. `pv_live_…` or `pv_test_…`. Throws `PromptVaultError("missing_key")` if empty.
`cache`	`boolean \| CacheOptions`	`true`	Downtime-only fallback by default (`ttl: 0`). See Caching.
`timeout`	`number` (ms)	`100`	Per-request hard timeout (`DEFAULT_TIMEOUT_MS`). A read that doesn't complete is aborted and surfaced as `transport_error`, so the cache fallback kicks in.

`PromptVaultClient`

The class returned by promptvault(...). You normally don't instantiate it directly.

`.get(slug, options?)`

Returns the prompt's live (or staging) version, ready to send.

pv.get("support-triage");
pv.get("onboarding-email", { variables: { recipient_name: "Maya" } });
pv.get("onboarding-email", { interpolate: false });

Parameter	Type	Notes
`slug`	`string`	Workspace-unique identifier.
`options.interpolate`	`boolean`	Default `true`. When `false`, returns the source untouched.
`options.variables`	`Record<string, string \| number \| boolean>`	Default `{}`. Replaces `{{var}}` / `{var}` tokens. Unknown tokens are left as-is. Ignored when `interpolate` is `false`.

Returns Promise<Prompt>. Throws PromptVaultError("not_found") if the slug is unknown.

`.version(slug, label, options?)`

Fetches a specific historical version. Same options as .get().

const v21 = await pv.version("support-triage", "v21");
const rendered = await pv.version("onboarding-email", "v8", {
  variables: { recipient_name: "Maya" },
});

Returns Promise<Prompt>. Throws PromptVaultError("version_not_found") if the label doesn't exist on this prompt.

`.listVersions(slug)`

Lists every version of a prompt, newest first.

const versions = await pv.listVersions("support-triage");
// [
//   {
//     label: "v22",
//     message: "refund-policy citations",
//     author: "maya",
//     source: "…",        // system + user concatenated
//     system: "…",        // system role content
//     user: "…",          // user role content ("" if none)
//     createdAt: "2026-04-29T10:00:00.000Z"
//   },
//   …
// ]

Returns Promise<Version[]>, newest first.

Types

`Prompt`

interface Prompt {
  slug: string;
  folder: string;
  model: string;
  temperature: number;
  version: string;       // 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: Message[];   // ordered system → user; empty roles omitted
  variables: string[];   // detected token names
}

interpolate: false and variables apply consistently to source, systemSource, userSource, and messages. A legacy single-prompt entry (no user role) yields a one-element messages array with role: "system".

`Message` / `MessageRole`

type MessageRole = "system" | "user";

interface Message {
  role: MessageRole;
  content: string;
}

`PromptSummary`

interface PromptSummary {
  slug: string;
  folder: string;
  model: string;
  liveVersion: string;
  stagingVersion?: string;
}

`Version`

interface Version {
  label: string;
  message: string;   // commit-style description
  author: string;
  source: string;    // system + user concatenated
  system: string;    // system role content
  user: string;      // user role content ("" if none)
  createdAt: string; // ISO-8601
}

`GetOptions`

interface GetOptions {
  interpolate?: boolean;
  variables?: Record<string, string | number | boolean>;
}

`VariableValue`

type VariableValue = string | number | boolean;

Cache types

type CacheConfig = boolean | CacheOptions;

interface CacheOptions {
  enabled?: boolean;             // false ⇒ no cache (same as cache: false)
  store?: CacheStore;            // defaults to MemoryCacheStore
  ttl?: number;                  // freshness window (ms); default 0 (downtime-only)
  staleWhileRevalidate?: number; // serve-stale window (ms) past ttl; default 0; requires ttl > 0
}

interface CacheStore {
  get(key: string): CacheEntry | undefined | Promise<CacheEntry | undefined>;
  set(key: string, entry: CacheEntry): void | Promise<void>;
  delete?(key: string): void | Promise<void>;
}

interface CacheEntry<T = unknown> {
  value: T;
  storedAt?: number; // epoch ms; omitted ⇒ unknown age (fallback-only)
}

See Caching for the full behaviour rules.

Advanced exports

These are exported from the package root for lower-level use; most apps never need them.

Export	Kind	What it's for
`HttpTransport`	class	The HTTP read path. Implements `Transport`. Construct with `{ key, timeout?, fetch? }` (`HttpTransportOptions`) to inject a custom `fetch`.
`DEFAULT_TIMEOUT_MS`	const	The default per-request timeout - `100`.
`pullSnapshot(options)`	function	Lists the prompts the key can read (optionally scoped to one `folder`) and packages them into a `PromptVaultSnapshot` for offline/committed use. Accepts `PullSnapshotOptions` (`PromptVaultOptions` plus an optional `folder` scope and a `transport` override). With the default `HttpTransport`, each record carries the prompt's `liveVersion` / `stagingVersion` labels; full per-version history requires a transport that populates `versions`.
`SNAPSHOT_SCHEMA`	const	The snapshot wire-format tag, `"promptvault-snapshot-v1"`.
`Transport`	type	The transport interface: `getPrompt`, `listPrompts`, `listVersions`.
`RawPromptRecord` / `RawVersion`	types	The unnormalized wire shapes a `Transport` returns.

All reads target the hosted API at https://app.promptvlt.com; the origin is not configurable.

Errors

Every SDK error is an instance of PromptVaultError:

class PromptVaultError extends Error {
  readonly code: "missing_key" | "not_found" | "version_not_found" | "transport_error";
}

See Errors for codes and recovery patterns.

Key Prefix Resolution

The key prefix decides which version .get() returns:

Prefix	Behaviour
`pv_live_`	Returns the live version.
`pv_test_`	Returns the staging version if set, otherwise the live version.