Integration Guide

Step-by-step guide to integrating the Converra SDK into your application.

Minimal Integration

The simplest way to integrate Converra - fetch prompts and log conversations:

import { Converra } from 'converra';

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

// 1. Fetch your prompt (cached for 5 minutes by default)
const prompt = await converra.prompts.get('prompt_123');

// 2. Use the prompt in your AI application
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'system', content: prompt.content },
    { role: 'user', content: userMessage }
  ]
});

// 3. Log the conversation for insights
await converra.conversations.create({
  promptId: 'prompt_123',
  content: `User: ${userMessage}\nAssistant: ${response.choices[0].message.content}`,
  status: 'completed'
});

Full Integration (Recommended)

For instant variant updates when optimizations complete, add webhook handling:

import { Converra, createWebhookHandler } from 'converra';

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

// Create webhook handler with automatic cache invalidation
const webhookHandler = createWebhookHandler({
  secret: process.env.CONVERRA_WEBHOOK_SECRET,

  // Invalidate cache when a variant is applied
  onPromptUpdated: (data) => {
    converra.cache.invalidate(data.promptId);
    console.log(`Prompt ${data.promptId} updated - cache invalidated`);
  },

  // Get notified when optimization completes
  onOptimizationCompleted: (data) => {
    if (data.results.winningVariantId) {
      console.log(`Optimization complete! ${data.results.improvementPercentage}% improvement`);
    }
  },
});

// Register the webhook endpoint (Express example)
app.post('/webhooks/converra', express.raw({ type: 'application/json' }), async (req, res) => {
  const result = await webhookHandler(req.body, req.headers['x-converra-signature']);
  res.status(result.success ? 200 : 400).json(result);
});

Next.js App Router

// app/api/webhooks/converra/route.ts
import { createWebhookHandler } from 'converra';
import { converra } from '@/lib/converra'; // your singleton instance

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

export async function POST(req: Request) {
  const body = await req.text();
  const signature = req.headers.get('x-converra-signature') || '';
  const result = await handler(body, signature);
  return Response.json(result, { status: result.success ? 200 : 400 });
}

Express.js

// routes/webhooks.ts
import express from 'express';
import { createWebhookHandler } from 'converra';
import { converra } from '../lib/converra';

const router = express.Router();

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

router.post(
  '/converra',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const result = await handler(req.body, req.headers['x-converra-signature']);
    res.status(result.success ? 200 : 400).json(result);
  }
);

export default router;

Singleton Pattern

Create a single SDK instance to share across your application:

// lib/converra.ts
import { Converra } from 'converra';

export const converra = new Converra({
  apiKey: process.env.CONVERRA_API_KEY!,
  cache: { strategy: 'memory', ttl: 5 * 60 * 1000 }
});

Then import it wherever needed:

import { converra } from '@/lib/converra';

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