@promptv/sdk

Runtime prompt resolution and outcome tracking for Prompt Vault.

• Fetch the live version of a prompt with context-aware A/B routing
• Track latency, tokens, and outcome scores per variant
• Automatic client-side caching with configurable TTL
• Isomorphic — works in Node 18+ and modern browsers
• ESM + CJS builds, full TypeScript types

Install

npm install @promptv/sdk
# or
yarn add @promptv/sdk
# or
pnpm add @promptv/sdk

Quick start

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

const pv = new PromptVault({
  apiKey: process.env.PROMPT_VAULT_API_KEY!,
  apiUrl: "https://your-prompt-vault.com", // defaults to http://localhost:3000
});

// Resolve the live version for a given slug and context
const prompt = await pv.get("summarize-article", {
  context: { userId: "usr_123", plan: "pro" },
});

// …send prompt.text / prompt.model / prompt.temperature to your LLM provider

// Report the outcome once you have it
await pv.track(prompt.promptId, {
  latencyMs: 832,
  tokens: 412,
  outcomeScore: 0.92,
  observabilityProvider: "helicone",
});

API

new PromptVault(options)

| Option | Type | Default | Description | | -------- | ------------------- | ----------------------- | ----------------------------------------------------- | | apiKey | string (required) | — | Project API key from your Prompt Vault dashboard. | | apiUrl | string | http://localhost:3000 | Base URL of your Prompt Vault instance. | | ttlMs | number | 30_000 | Default cache TTL when the server doesn't return one. | | fetch | typeof fetch | global fetch | Custom fetch implementation (useful for Node <18). |

pv.get(promptSlug, { context?, bypassCache? })

Returns the resolved PromptVaultPrompt. Responses are cached per (slug, context) pair using a stable JSON stringify.

pv.track(promptId, input)

Sends an outcome event. input accepts tokens, latencyMs, outcomeScore, metadata, and observabilityProvider.

pv.clearCache(promptSlug?)

Clears the in-memory cache. Pass a slug to scope the invalidation.

License

MIT © Artem