integrations.md

VLY Integrations

First-order integrations for AI, email, and payments with automatic usage billing through VLY integration keys.

Environment Variables

The following environment variables are automatically set during project creation:

• VLY_INTEGRATION_KEY: Your unique integration key (format: sk_*)
• VLY_INTEGRATION_BASE_URL: The base URL for the integration gateway (default: https://integrations.vly.ai/)

Installation

The @vly-ai/integrations package is already included in package.json.

Alternative AI Providers: While you can use OpenAI, OpenRouter, or other AI providers directly with your own API keys, @vly-ai/integrations is simpler as it works out-of-the-box without requiring you to supply and manage API keys.

Usage in Convex Actions

"use node";

import { vly } from '../lib/vly-integrations';
import { action } from "./_generated/server";

export const generateAIResponse = action({
handler: async (ctx, args) => {
  // AI Completions
  const completion = await vly.ai.completion({
    model: 'gpt-4o-mini',
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'Hello!' }
    ],
    temperature: 0.7,
    maxTokens: 150
  });

  return completion;
}
});

Available Features

AI Integration

// Create completion
const completion = await vly.ai.completion({
model: 'gpt-4o-mini', // or 'gpt-4o', 'claude-3-haiku', etc.
messages: [...],
temperature: 0.7,
maxTokens: 150
});

// Stream completion
await vly.ai.streamCompletion(
request,
(chunk: string) => console.log(chunk)
);

// Generate embeddings
const embeddings = await vly.ai.embeddings("Your text here");

Email Integration

// Send email
const emailResult = await vly.email.send({
to: 'user@example.com',
subject: 'Welcome!',
html: '<h1>Welcome to our service!</h1>',
text: 'Welcome to our service!'
});

// Send batch emails
const batchResult = await vly.email.sendBatch([...emails]);

Payments Integration

// Create payment intent
const paymentIntent = await vly.payments.createPaymentIntent({
amount: 2000, // $20.00 in cents
currency: 'usd',
description: 'Premium subscription',
customer: {
  email: 'customer@example.com'
}
});

// Create subscription
const subscription = await vly.payments.createSubscription({...});

// Create checkout session
const session = await vly.payments.createCheckoutSession({...});

Error Handling

All methods return an ApiResponse object:

interface ApiResponse<T> {
success: boolean;
data?: T;
error?: string;
usage?: {
  credits: number;
  operation: string;
};
}

Example error handling:

const result = await vly.ai.completion({ ... });

if (result.success) {
console.log('Response:', result.data);
console.log('Credits used:', result.usage?.credits);
} else {
console.error('Error:', result.error);
}

Important Notes

1. The integration key (VLY_INTEGRATION_KEY) is automatically injected during project creation
2. All API calls are automatically billed to your deployment based on usage
3. Must be used in Convex actions with "use node" directive
4. The integration key should never be exposed to the client
5. Alternative AI providers: While you can use OpenAI, OpenRouter, or other AI providers directly with your own API keys, @vly-ai/integrations is simpler as it works out-of-the-box without requiring you to supply and manage API keys

Checking Integration Status

To verify the integration is properly configured:

const hasIntegration = !!process.env.VLY_INTEGRATION_KEY;
if (!hasIntegration) {
console.error("VLY integration key not found");
}