Caching

The SDK includes built-in caching for prompts to minimize API calls and improve performance.

Configuration

const converra = new Converra({
  apiKey: process.env.CONVERRA_API_KEY,
  cache: {
    strategy: 'memory',  // Default: in-memory cache
    ttl: 5 * 60 * 1000   // Default: 5 minutes
  }
});

Cache Strategies

Strategy	Description
memory	In-memory cache (default). Fast, cleared on restart.
none	No caching. Every get() call hits the API.

Basic Usage

// Cached automatically
const prompt = await converra.prompts.get('prompt_123');

// Bypass cache when needed
const fresh = await converra.prompts.get('prompt_123', { bypassCache: true });

Manual Cache Operations

// Invalidate specific prompt
converra.cache.invalidate('prompt_123');

// Clear all cached prompts
converra.cache.invalidateAll();

// Get cache statistics
const stats = converra.cache.stats();
// { size: 5, enabled: true, ttl: 300000 }

Disable Caching

const converra = new Converra({
  apiKey: process.env.CONVERRA_API_KEY,
  cache: { strategy: 'none' }
});

Webhook-Based Invalidation

For real-time cache updates when prompts change, use webhooks:

import { Converra, createWebhookHandler } from 'converra';

const converra = new Converra({
  apiKey: process.env.CONVERRA_API_KEY
});

const webhookHandler = createWebhookHandler({
  secret: process.env.CONVERRA_WEBHOOK_SECRET,
  onPromptUpdated: (data) => {
    converra.cache.invalidate(data.promptId);
  }
});

This ensures your application always uses the latest prompt content immediately after an optimization applies a winning variant.

Best Practices

1. Use the default TTL (5 min) for most applications
2. Set up webhooks to invalidate cache when prompts update
3. Use bypassCache sparingly - only when you need guaranteed fresh data
4. Monitor cache stats to ensure good hit rates